dep-brain 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,9 +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.
+# 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

@@ -1,21 +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.
+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

@@ -1,197 +1,198 @@
-# 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)
+# 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
+dep-brain --version
+```
+
+## 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

@@ -1,20 +1,20 @@
-{
-  "ignore": {
-    "unused": [],
-    "outdated": [],
-    "duplicates": [],
-    "risks": [],
-    "dependencies": [],
-    "devDependencies": []
-  },
-  "policy": {
-    "minScore": 85,
-    "failOnUnused": false,
-    "failOnOutdated": false,
-    "failOnDuplicates": false,
-    "failOnRisks": false
-  },
-  "report": {
-    "maxSuggestions": 5
-  }
-}
+{
+  "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

@@ -1,38 +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" }
-      }
-    }
-  }
-}
+{
+  "$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/cli.js

@@ -6,11 +6,13 @@ 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 firstArg = args[0];
+    const command = firstArg && !firstArg.startsWith("--") ? firstArg : "analyze";
     const optionValues = new Map();
     const flags = new Set();
     const positionals = [];
-    for (let index = 1; index < args.length; index += 1) {
+    const startIndex = firstArg && !firstArg.startsWith("--") ? 1 : 0;
+    for (let index = startIndex; index < args.length; index += 1) {
         const value = args[index];
         if (!value?.startsWith("--")) {
             positionals.push(value);
@@ -30,6 +32,11 @@ async function main() {
         printHelp();
         return;
     }
+    if (flags.has("--version")) {
+        const version = await loadPackageVersion();
+        console.log(version ?? "unknown");
+        return;
+    }
     if (command !== "analyze") {
         if (command === "config") {
             if (!(await hasPackageJson(targetPath))) {
@@ -37,13 +44,21 @@ async function main() {
                 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;
+            try {
+                const config = await analyzeProject({
+                    rootDir: targetPath,
+                    configPath: optionValues.get("--config"),
+                    config: buildCliConfig(flags, optionValues)
+                });
+                console.log(JSON.stringify(config.config, null, 2));
+                return;
+            }
+            catch (error) {
+                console.error("Failed to resolve config.");
+                console.error(error);
+                process.exitCode = 1;
+                return;
+            }
         }
         console.error(`Unknown command: ${command}`);
         printHelp();
@@ -55,14 +70,21 @@ async function main() {
         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) {
+    try {
+        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;
+        }
+    }
+    catch (error) {
+        console.error("Analysis failed.");
+        console.error(error);
         process.exitCode = 1;
     }
 }
@@ -105,6 +127,7 @@ function printHelp() {
     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("  dep-brain --version");
     console.log("");
     console.log("Options:");
     console.log("  --json              Output JSON for analysis");
@@ -115,4 +138,16 @@ function printHelp() {
     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");
+    console.log("  --version           Show CLI version");
+}
+async function loadPackageVersion() {
+    try {
+        const pkgPath = new URL("../package.json", import.meta.url);
+        const content = await fs.readFile(pkgPath, "utf8");
+        const pkg = JSON.parse(content);
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
 }

package/package.json

@@ -1,53 +1,53 @@
-{
-  "name": "dep-brain",
-  "version": "0.1.0",
-  "description": "CLI and library for dependency health analysis",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "dep-brain": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md",
-    "depbrain.config.json",
-    "depbrain.config.schema.json"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "clean": "if exist dist rmdir /s /q dist",
-    "dev": "tsx src/cli.ts analyze",
-    "start": "node dist/cli.js analyze",
-    "test": "npm run build && node tests/run.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
-  "keywords": [
-    "dependencies",
-    "cli",
-    "analysis",
-    "npm",
-    "audit"
-  ],
-  "author": "",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+ssh://git@github.com/prakashu51/dep-brain.git"
-  },
-  "bugs": {
-    "url": "https://github.com/prakashu51/dep-brain/issues"
-  },
-  "homepage": "https://github.com/prakashu51/dep-brain#readme",
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {},
-  "devDependencies": {
-    "@types/node": "^24.5.2",
-    "tsx": "^4.20.5",
-    "typescript": "^5.9.2"
-  }
-}
+{
+  "name": "dep-brain",
+  "version": "0.1.2",
+  "description": "CLI and library for dependency health analysis",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dep-brain": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "depbrain.config.json",
+    "depbrain.config.schema.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "if exist dist rmdir /s /q dist",
+    "dev": "tsx src/cli.ts analyze",
+    "start": "node dist/cli.js analyze",
+    "test": "npm run build && node tests/run.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": [
+    "dependencies",
+    "cli",
+    "analysis",
+    "npm",
+    "audit"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/prakashu51/dep-brain.git"
+  },
+  "bugs": {
+    "url": "https://github.com/prakashu51/dep-brain/issues"
+  },
+  "homepage": "https://github.com/prakashu51/dep-brain#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}