dep-brain 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+- Workspace-aware analysis for npm workspaces.
+- Config loading and CI policy controls.
+- Improved duplicate detection and unused dependency heuristics.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay prakash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# Dependency Brain
+
+[![npm version](https://img.shields.io/npm/v/dep-brain)](https://www.npmjs.com/package/dep-brain)
+[![npm downloads](https://img.shields.io/npm/dm/dep-brain)](https://www.npmjs.com/package/dep-brain)
+[![license](https://img.shields.io/npm/l/dep-brain)](LICENSE)
+
+`dep-brain` is a CLI and library for analyzing dependency health in JavaScript and TypeScript projects.
+
+## Vision
+
+`npm audit + depcheck + dedupe + intelligence = one tool`
+
+## What It Does
+
+- Detect duplicate dependencies from `package-lock.json`
+- Detect likely unused dependencies from source imports and scripts
+- Detect outdated packages
+- Highlight dependency risk signals
+- Generate a simple project health score
+- Output reports in human-readable or JSON format
+
+## Current MVP 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
+- 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`
+- Library entrypoint for programmatic use
+
+## CLI Usage
+
+```bash
+npm install -g dep-brain
+dep-brain analyze
+
+npx dep-brain analyze
+npx dep-brain analyze --json
+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
+npx dep-brain analyze ./path-to-project --fail-on-unused --json
+
+dep-brain config
+dep-brain config --config depbrain.config.json
+
+dep-brain help
+dep-brain analyze --help
+```
+
+## Workspaces
+
+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.
+
+## Example Output
+
+```text
+Project Health: 78/100
+Path: /your/project
+Policy: FAIL
+
+WARN Duplicates: 2
+OK Unused: 0
+WARN Outdated: 3
+OK Risks: 0
+
+Duplicate dependencies:
+- ansi-regex: 5.0.1, 6.0.1
+
+Outdated dependencies:
+- chalk: ^4.1.2 -> 5.4.1 [major]
+
+Policy reasons:
+- Score 78 is below minimum 90
+
+Suggestions:
+- Consider consolidating ansi-regex to one version
+- Review chalk: ^4.1.2 -> 5.4.1 (major)
+```
+
+## JSON Output
+
+```bash
+dep-brain analyze --json
+```
+
+## Config File
+
+Create a `depbrain.config.json` file in the project root:
+
+```json
+{
+  "ignore": {
+    "unused": ["eslint"],
+    "outdated": ["typescript"]
+  },
+  "policy": {
+    "minScore": 90,
+    "failOnUnused": true,
+    "failOnRisks": true
+  },
+  "report": {
+    "maxSuggestions": 3
+  }
+}
+```
+
+Supported sections:
+
+- `ignore.dependencies`
+- `ignore.devDependencies`
+- `ignore.unused`
+- `ignore.duplicates`
+- `ignore.outdated`
+- `ignore.risks`
+- `policy.minScore`
+- `policy.failOnDuplicates`
+- `policy.failOnUnused`
+- `policy.failOnOutdated`
+- `policy.failOnRisks`
+- `report.maxSuggestions`
+
+Sample config file:
+
+- `depbrain.config.json`
+- `depbrain.config.schema.json`
+
+## CI Behavior
+
+`dep-brain` now returns a non-zero exit code when configured policy checks fail.
+
+Examples:
+
+```bash
+dep-brain analyze --fail-on-unused
+dep-brain analyze --min-score 85 --fail-on-risks
+dep-brain analyze --config depbrain.config.json
+```
+
+## Config Debugging
+
+Print the resolved config (after defaults and CLI overrides):
+
+```bash
+dep-brain config
+dep-brain config --config depbrain.config.json
+```
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run test
+npm run build
+```
+
+## Project Structure
+
+```text
+src/
+|-- cli.ts
+|-- index.ts
+|-- core/
+|   |-- analyzer.ts
+|   |-- graph-builder.ts
+|   `-- scorer.ts
+|-- checks/
+|   |-- duplicate.ts
+|   |-- unused.ts
+|   |-- outdated.ts
+|   `-- risk.ts
+|-- reporters/
+|   |-- console.ts
+|   `-- json.ts
+`-- utils/
+    |-- file-parser.ts
+    |-- npm-api.ts
+    `-- config.ts
+```
+
+## Roadmap Direction
+
+- Improve false-positive reduction for unused dependency detection
+- Improve monorepo and workspace support
+- Strengthen risk scoring and suggestions
+- Add CI and GitHub Action support in later releases
+
+## Repository Notes
+
+- Project brief: [docs/project-brief.md](./docs/project-brief.md)
+- Implementation history: [docs/implementation-log.md](./docs/implementation-log.md)

package/depbrain.config.json

@@ -0,0 +1,20 @@
+{
+  "ignore": {
+    "unused": [],
+    "outdated": [],
+    "duplicates": [],
+    "risks": [],
+    "dependencies": [],
+    "devDependencies": []
+  },
+  "policy": {
+    "minScore": 85,
+    "failOnUnused": false,
+    "failOnOutdated": false,
+    "failOnDuplicates": false,
+    "failOnRisks": false
+  },
+  "report": {
+    "maxSuggestions": 5
+  }
+}

package/depbrain.config.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Dependency Brain Config",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "ignore": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "dependencies": { "type": "array", "items": { "type": "string" } },
+        "devDependencies": { "type": "array", "items": { "type": "string" } },
+        "unused": { "type": "array", "items": { "type": "string" } },
+        "duplicates": { "type": "array", "items": { "type": "string" } },
+        "outdated": { "type": "array", "items": { "type": "string" } },
+        "risks": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "minScore": { "type": "number" },
+        "failOnUnused": { "type": "boolean" },
+        "failOnOutdated": { "type": "boolean" },
+        "failOnDuplicates": { "type": "boolean" },
+        "failOnRisks": { "type": "boolean" }
+      }
+    },
+    "report": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxSuggestions": { "type": "number" }
+      }
+    }
+  }
+}

package/dist/checks/duplicate.d.ts

@@ -0,0 +1,3 @@
+import type { DuplicateDependency } from "../core/analyzer.js";
+import type { DependencyGraph } from "../core/graph-builder.js";
+export declare function findDuplicateDependencies(graph: DependencyGraph): Promise<DuplicateDependency[]>;

package/dist/checks/duplicate.js

@@ -0,0 +1,10 @@
+export async function findDuplicateDependencies(graph) {
+    return Object.entries(graph.lockPackages)
+        .map(([name, instances]) => ({
+        name,
+        versions: Array.from(new Set(instances.map((instance) => instance.version))).sort(),
+        instances
+    }))
+        .filter((dependency) => dependency.versions.length > 1)
+        .sort((left, right) => left.name.localeCompare(right.name));
+}

package/dist/checks/outdated.d.ts

@@ -0,0 +1,6 @@
+import type { OutdatedDependency } from "../core/analyzer.js";
+import type { DependencyGraph } from "../core/graph-builder.js";
+export interface OutdatedOptions {
+    resolveLatestVersion?: (name: string) => Promise<string | null>;
+}
+export declare function findOutdatedDependencies(graph: DependencyGraph, options?: OutdatedOptions): Promise<OutdatedDependency[]>;

package/dist/checks/outdated.js

@@ -0,0 +1,51 @@
+import { getLatestVersion } from "../utils/npm-api.js";
+export async function findOutdatedDependencies(graph, options = {}) {
+    const resolveLatestVersion = options.resolveLatestVersion ?? getLatestVersion;
+    const combined = {
+        ...graph.dependencies,
+        ...graph.devDependencies
+    };
+    const results = await Promise.all(Object.entries(combined).map(async ([name, current]) => {
+        const normalized = normalizeVersion(current);
+        const latest = await resolveLatestVersion(name);
+        if (!latest || latest === normalized) {
+            return null;
+        }
+        return {
+            name,
+            current,
+            latest,
+            updateType: classifyUpdateType(normalized, latest)
+        };
+    }));
+    return results
+        .filter((item) => item !== null)
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function normalizeVersion(versionRange) {
+    return versionRange.trim().replace(/^[~^><=\s]+/, "");
+}
+function classifyUpdateType(currentVersion, latestVersion) {
+    const current = parseVersion(currentVersion);
+    const latest = parseVersion(latestVersion);
+    if (!current || !latest) {
+        return "unknown";
+    }
+    if (latest[0] !== current[0]) {
+        return "major";
+    }
+    if (latest[1] !== current[1]) {
+        return "minor";
+    }
+    if (latest[2] !== current[2]) {
+        return "patch";
+    }
+    return "unknown";
+}
+function parseVersion(version) {
+    const match = version.match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+        return null;
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}

package/dist/checks/risk.d.ts

@@ -0,0 +1,3 @@
+import type { DependencyGraph } from "../core/graph-builder.js";
+import type { RiskDependency } from "../core/analyzer.js";
+export declare function findRiskDependencies(graph: DependencyGraph): Promise<RiskDependency[]>;

package/dist/checks/risk.js

@@ -0,0 +1,31 @@
+import { getPackageMetadata } from "../utils/npm-api.js";
+const TWO_YEARS_IN_DAYS = 365 * 2;
+export async function findRiskDependencies(graph) {
+    const names = Object.keys({
+        ...graph.dependencies,
+        ...graph.devDependencies
+    });
+    const results = await Promise.all(names.map(async (name) => {
+        const metadata = await getPackageMetadata(name);
+        const reasons = [];
+        if (!metadata) {
+            return null;
+        }
+        if (metadata.daysSincePublish !== null && metadata.daysSincePublish > TWO_YEARS_IN_DAYS) {
+            reasons.push("No release in over 2 years");
+        }
+        if (metadata.downloads !== null && metadata.downloads < 1000) {
+            reasons.push("Low weekly download volume");
+        }
+        if (!metadata.repository) {
+            reasons.push("Missing repository metadata");
+        }
+        if (reasons.length === 0) {
+            return null;
+        }
+        return { name, reasons };
+    }));
+    return results
+        .filter((item) => item !== null)
+        .sort((left, right) => left.name.localeCompare(right.name));
+}

package/dist/checks/unused.d.ts

@@ -0,0 +1,3 @@
+import type { UnusedDependency } from "../core/analyzer.js";
+import type { DependencyGraph } from "../core/graph-builder.js";
+export declare function findUnusedDependencies(rootDir: string, graph: DependencyGraph): Promise<UnusedDependency[]>;

package/dist/checks/unused.js

@@ -0,0 +1,120 @@
+import path from "node:path";
+import { collectProjectFiles, readTextFile } from "../utils/file-parser.js";
+const SOURCE_FILE_PATTERN = /\.(c|m)?(t|j)sx?$/;
+const CONFIG_FILE_PATTERN = /(^|[\\/])(vite|vitest|jest|eslint|prettier|rollup|webpack|babel|tsup|eslint\.config|commitlint|playwright|storybook|tailwind|postcss)\.config\.(c|m)?(t|j)s$/;
+const TEST_FILE_PATTERN = /(^|[\\/])(__tests__|test|tests|spec|specs)([\\/]|$)|\.(test|spec)\.(c|m)?(t|j)sx?$/;
+const RUNTIME_DIR_PATTERN = /(^|[\\/])(src|app|lib|server|client|pages|components)([\\/]|$)/;
+export async function findUnusedDependencies(rootDir, graph) {
+    const files = await collectProjectFiles(rootDir, SOURCE_FILE_PATTERN);
+    const projectFiles = files.filter((filePath) => !filePath.includes(`${path.sep}node_modules${path.sep}`));
+    const runtimeUsed = new Set();
+    const devUsed = new Set();
+    for (const filePath of projectFiles) {
+        const content = await readTextFile(filePath);
+        const imports = extractImportedPackages(content);
+        const isDevOnlyFile = isDevelopmentOnlyFile(rootDir, filePath);
+        const target = isDevOnlyFile ? devUsed : runtimeUsed;
+        for (const importedPackage of imports) {
+            target.add(importedPackage);
+            if (!isDevOnlyFile) {
+                devUsed.add(importedPackage);
+            }
+        }
+    }
+    for (const referencedBinary of extractScriptReferences(graph.scripts)) {
+        devUsed.add(referencedBinary);
+    }
+    const hasTypeScriptSources = projectFiles.some((filePath) => /\.(c|m)?tsx?$/.test(filePath));
+    const hasTypeScriptConfig = await hasFile(rootDir, "tsconfig.json");
+    if (hasTypeScriptConfig) {
+        devUsed.add("typescript");
+    }
+    const unusedDependencies = Object.keys(graph.dependencies)
+        .filter((name) => !runtimeUsed.has(name))
+        .map((name) => ({ name, section: "dependencies" }));
+    const unusedDevDependencies = Object.keys(graph.devDependencies)
+        .filter((name) => !devUsed.has(name) && !runtimeUsed.has(name))
+        .filter((name) => !isImplicitlyUsedDevDependency(name, hasTypeScriptSources, hasTypeScriptConfig))
+        .map((name) => ({ name, section: "devDependencies" }));
+    return [...unusedDependencies, ...unusedDevDependencies].sort((left, right) => left.name.localeCompare(right.name));
+}
+function extractImportedPackages(content) {
+    const imports = new Set();
+    const patterns = [
+        /\bimport\s+[^"'`]*?from\s+["'`]([^"'`]+)["'`]/g,
+        /\bexport\s+[^"'`]*?from\s+["'`]([^"'`]+)["'`]/g,
+        /\bimport\s*\(\s*["'`]([^"'`]+)["'`]\s*\)/g,
+        /\brequire\(\s*["'`]([^"'`]+)["'`]\s*\)/g,
+        /\bimport\s+["'`]([^"'`]+)["'`]/g
+    ];
+    for (const pattern of patterns) {
+        for (const match of content.matchAll(pattern)) {
+            const dependencyName = normalizeModuleSpecifier(match[1]);
+            if (dependencyName) {
+                imports.add(dependencyName);
+            }
+        }
+    }
+    return imports;
+}
+function normalizeModuleSpecifier(specifier) {
+    if (!specifier ||
+        specifier.startsWith(".") ||
+        specifier.startsWith("/") ||
+        specifier.startsWith("#")) {
+        return null;
+    }
+    if (specifier.startsWith("@")) {
+        const [scope, name] = specifier.split("/");
+        return scope && name ? `${scope}/${name}` : null;
+    }
+    return specifier.split("/")[0] ?? null;
+}
+function isDevelopmentOnlyFile(rootDir, filePath) {
+    const relativePath = path.relative(rootDir, filePath);
+    return (TEST_FILE_PATTERN.test(relativePath) ||
+        CONFIG_FILE_PATTERN.test(relativePath) ||
+        (!RUNTIME_DIR_PATTERN.test(relativePath) && relativePath.includes("scripts")));
+}
+function extractScriptReferences(scripts) {
+    const references = new Set();
+    for (const script of Object.values(scripts)) {
+        for (const token of script.split(/[^@\w./-]+/).filter(Boolean)) {
+            const normalized = normalizeScriptToken(token);
+            if (normalized) {
+                references.add(normalized);
+            }
+        }
+    }
+    return references;
+}
+function normalizeScriptToken(token) {
+    if (!token || token.startsWith(".") || token.includes("=") || token.startsWith("node")) {
+        return null;
+    }
+    if (token.startsWith("@")) {
+        const scopedMatch = token.match(/^(@[^/]+\/[^/]+)/);
+        if (scopedMatch) {
+            return scopedMatch[1];
+        }
+    }
+    return token.replace(/\.cmd$/i, "");
+}
+function isImplicitlyUsedDevDependency(name, hasTypeScriptSources, hasTypeScriptConfig) {
+    if (name === "typescript" && (hasTypeScriptSources || hasTypeScriptConfig)) {
+        return true;
+    }
+    if (name.startsWith("@types/") && hasTypeScriptSources) {
+        return true;
+    }
+    return false;
+}
+async function hasFile(rootDir, fileName) {
+    try {
+        await readTextFile(path.join(rootDir, fileName));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { analyzeProject } from "./core/analyzer.js";
+import { renderConsoleReport } from "./reporters/console.js";
+import { renderJsonReport } from "./reporters/json.js";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0] ?? "analyze";
+    const optionValues = new Map();
+    const flags = new Set();
+    const positionals = [];
+    for (let index = 1; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value?.startsWith("--")) {
+            positionals.push(value);
+            continue;
+        }
+        const nextValue = args[index + 1];
+        if (nextValue && !nextValue.startsWith("--")) {
+            optionValues.set(value, nextValue);
+            index += 1;
+            continue;
+        }
+        flags.add(value);
+    }
+    const targetPath = positionals[0] ?? process.cwd();
+    const showHelp = flags.has("--help") || command === "help";
+    if (showHelp) {
+        printHelp();
+        return;
+    }
+    if (command !== "analyze") {
+        if (command === "config") {
+            if (!(await hasPackageJson(targetPath))) {
+                console.error(`No package.json found at ${targetPath}`);
+                process.exitCode = 1;
+                return;
+            }
+            const config = await analyzeProject({
+                rootDir: targetPath,
+                configPath: optionValues.get("--config"),
+                config: buildCliConfig(flags, optionValues)
+            });
+            console.log(JSON.stringify(config.config, null, 2));
+            return;
+        }
+        console.error(`Unknown command: ${command}`);
+        printHelp();
+        process.exitCode = 1;
+        return;
+    }
+    if (!(await hasPackageJson(targetPath))) {
+        console.error(`No package.json found at ${targetPath}`);
+        process.exitCode = 1;
+        return;
+    }
+    const cliConfig = buildCliConfig(flags, optionValues);
+    const result = await analyzeProject({
+        rootDir: targetPath,
+        configPath: optionValues.get("--config"),
+        config: cliConfig
+    });
+    console.log(flags.has("--json") ? renderJsonReport(result) : renderConsoleReport(result));
+    if (!result.policy.passed) {
+        process.exitCode = 1;
+    }
+}
+void main();
+function buildCliConfig(flags, optionValues) {
+    const minScore = optionValues.get("--min-score");
+    const policy = {};
+    if (minScore) {
+        policy.minScore = Number(minScore);
+    }
+    if (flags.has("--fail-on-duplicates")) {
+        policy.failOnDuplicates = true;
+    }
+    if (flags.has("--fail-on-outdated")) {
+        policy.failOnOutdated = true;
+    }
+    if (flags.has("--fail-on-risks")) {
+        policy.failOnRisks = true;
+    }
+    if (flags.has("--fail-on-unused")) {
+        policy.failOnUnused = true;
+    }
+    return {
+        policy
+    };
+}
+async function hasPackageJson(targetPath) {
+    try {
+        await fs.access(path.join(targetPath, "package.json"));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function printHelp() {
+    console.log("Dependency Brain");
+    console.log("");
+    console.log("Usage:");
+    console.log("  dep-brain analyze [path] [--json] [--config path] [--min-score n] [--fail-on-risks] [--fail-on-outdated] [--fail-on-unused] [--fail-on-duplicates]");
+    console.log("  dep-brain config [path] [--config path]");
+    console.log("  dep-brain help");
+    console.log("");
+    console.log("Options:");
+    console.log("  --json              Output JSON for analysis");
+    console.log("  --config <path>     Path to depbrain.config.json");
+    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");
+    console.log("  --fail-on-unused    Fail when unused dependencies exist");
+    console.log("  --fail-on-duplicates Fail when duplicates exist");
+    console.log("  --help              Show this help output");
+}