npm-package-doctor 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0 - Initial development version
+
+- Added dependency scanning
+- Added npm metadata analysis
+- Added health scoring
+- Added terminal, JSON, and HTML reports
+- Added branded CLI banner
+- Added tests and CI

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sri Pavan Tej Balam
+
+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,239 @@
+# npm-package-doctor
+
+[![CI](https://github.com/sripavantejb/npm-package-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/sripavantejb/npm-package-doctor/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A CLI that scans npm dependencies and generates package health, security, and maintainability reports.
+
+`npm-package-doctor` is an independent open-source CLI for the npm ecosystem. It is not official npm software.
+
+## Problem Statement
+
+Modern JavaScript projects often depend on dozens or hundreds of packages. A single dependency can introduce maintenance risk, license uncertainty, lifecycle scripts, stale releases, or supply-chain exposure. Developers need a quick way to inspect dependency health before upgrades, releases, and reviews.
+
+## Why This Exists
+
+`npm-package-doctor` turns dependency metadata into a readable health report. It combines package.json data, npm registry metadata, simple scoring rules, and professional report formats so teams can make better dependency decisions without digging through registry pages one package at a time.
+
+## Features
+
+- Scans `dependencies`, `devDependencies`, `optionalDependencies`, and `peerDependencies`
+- Supports custom project paths
+- Fetches npm registry metadata for each dependency
+- Scores package health from 0 to 100
+- Flags deprecated packages, missing licenses, missing repositories, stale publish dates, single-maintainer packages, high dependency counts, metadata failures, and install lifecycle scripts
+- Calculates an overall project score and risk level
+- Prints a polished terminal report
+- Writes valid JSON reports for scripts and dashboards
+- Creates a self-contained HTML report with inline CSS
+- Includes an interactive CLI banner for terminal reports
+- Ships with TypeScript types, tests, CI, and open-source project files
+
+## Installation
+
+Run with npx:
+
+```bash
+npx npm-package-doctor scan
+```
+
+Install globally:
+
+```bash
+npm install -g npm-package-doctor
+npm-package-doctor scan
+```
+
+For local development:
+
+```bash
+npm install
+npm run build
+node dist/cli.js scan --path .
+```
+
+## Usage
+
+```bash
+npm-package-doctor scan
+npm-package-doctor scan --path ./some-project
+npm-package-doctor scan --json
+npm-package-doctor scan --html
+npm-package-doctor scan --output report.json
+npm-package-doctor scan --output report.html
+npm-package-doctor scan --include-dev
+npm-package-doctor scan --only production
+npm-package-doctor scan --only development
+npm-package-doctor scan --no-banner
+```
+
+## CLI Options
+
+| Option | Description |
+| --- | --- |
+| `--path <path>` | Scan a project directory or a direct `package.json` path. Defaults to the current directory. |
+| `--json` | Print valid JSON to stdout, or write JSON when used with `--output`. |
+| `--html` | Generate a self-contained HTML report. |
+| `--output <file>` | Write the selected report to a file. `.json` and `.html` extensions are detected when no format flag is supplied. |
+| `--include-dev` | Compatibility alias. The default scan already includes development dependencies. |
+| `--only <scope>` | Limit the scan to `production` or `development` dependencies. |
+| `--no-banner` | Hide the interactive terminal banner. |
+
+## Example Terminal Output
+
+```text
+npm-package-doctor report
+
+Project: my-node-app
+Packages scanned: 42
+Overall score: 78/100
+Risk level: Medium
+
+Summary:
+  - Deprecated packages: 2
+  - Packages with install scripts: 3
+  - Packages with missing licenses: 1
+  - Inactive packages: 5
+
+High risk packages:
+
+  old-package (production)
+    Score: 42/100
+    Reasons:
+      - Package is deprecated.
+      - Last published more than 3 years ago.
+    Recommendations:
+      - Replace deprecated packages with maintained alternatives.
+```
+
+## JSON Report Usage
+
+Print JSON only:
+
+```bash
+npm-package-doctor scan --json
+```
+
+Write JSON:
+
+```bash
+npm-package-doctor scan --json --output report.json
+```
+
+JSON mode never prints the banner or colored terminal text, which makes it safe for scripts.
+
+## HTML Report Usage
+
+Generate the default HTML report:
+
+```bash
+npm-package-doctor scan --html
+```
+
+Choose the output file:
+
+```bash
+npm-package-doctor scan --html --output package-health-report.html
+```
+
+The HTML report is self-contained and includes the project summary, overall score, risk badges, dependency table, reasons, recommendations, author details, and timestamp.
+
+## Scoring Explanation
+
+Each package starts at 100 points. The score is reduced for clear, explainable signals:
+
+- Deprecated package
+- Metadata fetch failure
+- Missing license
+- Missing repository
+- Last publish date older than 1, 2, or 3 years
+- Requested version at least one major version behind latest
+- Single maintainer or no listed maintainers
+- High runtime dependency count
+- Install lifecycle scripts
+
+The project score is based on the average package score, with an additional penalty when critical-risk packages are present.
+
+## Risk Levels
+
+| Score | Risk level |
+| --- | --- |
+| 80 to 100 | Low |
+| 60 to 79 | Medium |
+| 40 to 59 | High |
+| 0 to 39 | Critical |
+
+## Example Use Cases
+
+- Review dependency health before a release
+- Compare risk before adding a new package
+- Produce a JSON report for internal dashboards
+- Attach an HTML report to a dependency review
+- Spot deprecated or inactive packages during maintenance
+- Review lifecycle scripts before running installs in sensitive environments
+
+## CLI Banner
+
+By default, npm-package-doctor shows a short interactive banner when printing terminal reports.
+
+Disable it with:
+
+```bash
+npm-package-doctor scan --no-banner
+```
+
+The banner is hidden for JSON output, CI environments, and non-interactive terminals.
+
+## Publishing Checklist
+
+Do not publish until final review.
+
+Before publishing:
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm pack --dry-run
+```
+
+When ready:
+
+```bash
+npm login
+npm version patch
+npm publish --access public
+```
+
+Use `npm version minor` or `npm version major` when the release size calls for it.
+
+## Roadmap
+
+- GitHub Action integration
+- Lockfile analysis
+- npm audit integration
+- SBOM generation
+- Package replacement suggestions
+- Web dashboard
+- Monorepo and workspaces support
+- Trusted publishing and provenance checks
+- Dependency diff between branches
+- Organization-level dependency reports
+
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, workflow, and pull request guidance.
+
+## Security Note
+
+This project provides risk signals from package metadata. It is not a complete security audit and should be used alongside code review, lockfile review, and vulnerability scanning. See [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Author
+
+Created by Sri Pavan Tej Balam  
+GitHub: [@sripavantejb](https://github.com/sripavantejb)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { Command, InvalidArgumentError } from "commander";
+import { renderHtmlReport } from "./reporters/htmlReporter.js";
+import { renderJsonReport } from "./reporters/jsonReporter.js";
+import { renderTerminalReport } from "./reporters/terminalReporter.js";
+import { scanProject } from "./scanner/scanProject.js";
+import { showBanner } from "./utils/banner.js";
+import { writeTextFile } from "./utils/fileUtils.js";
+import { formatError, writeError } from "./utils/logger.js";
+const packageVersion = "0.1.0";
+const program = new Command();
+program
+    .name("npm-package-doctor")
+    .description("Analyze npm dependencies and generate package health, security, and maintainability reports.")
+    .version(packageVersion);
+program
+    .command("scan")
+    .description("Scan npm dependencies in a Node.js project.")
+    .option("--path <path>", "Project path to scan.", process.cwd())
+    .option("--json", "Print or write a JSON report.")
+    .option("--html", "Generate an HTML report.")
+    .option("--output <file>", "Write the selected report to a file.")
+    .option("--include-dev", "Include development dependencies. Kept for compatibility; default scans all dependency sections.")
+    .option("--only <scope>", "Limit scan to production or development dependencies.", parseOnly)
+    .option("--no-banner", "Disable the interactive CLI banner.")
+    .action(async (options) => {
+    await runScan(options);
+});
+program.parseAsync(process.argv).catch((error) => {
+    writeError(formatError(error), false);
+    process.exitCode = 1;
+});
+async function runScan(options) {
+    const format = determineReportFormat(options);
+    try {
+        const report = await scanProject({
+            projectPath: options.path,
+            only: options.only,
+            includeDev: options.includeDev
+        });
+        if (format === "json") {
+            const json = renderJsonReport(report);
+            if (options.output) {
+                await writeTextFile(options.output, json);
+                return;
+            }
+            process.stdout.write(json);
+            return;
+        }
+        if (format === "html") {
+            const outputPath = options.output ?? "package-health-report.html";
+            const writtenPath = await writeTextFile(outputPath, renderHtmlReport(report));
+            process.stdout.write(`HTML report written to ${writtenPath}\n`);
+            return;
+        }
+        const terminalReport = renderTerminalReport(report);
+        if (options.output) {
+            const writtenPath = await writeTextFile(options.output, terminalReport);
+            process.stdout.write(`Terminal report written to ${writtenPath}\n`);
+            return;
+        }
+        showBanner({
+            disabled: options.banner === false,
+            json: false,
+            silent: format !== "terminal"
+        });
+        process.stdout.write(`${terminalReport}\n`);
+    }
+    catch (error) {
+        if (format === "json") {
+            process.stderr.write(`${formatError(error)}\n`);
+        }
+        else {
+            writeError(formatError(error));
+        }
+        process.exitCode = 1;
+    }
+}
+function determineReportFormat(options) {
+    if (options.json && options.html) {
+        throw new InvalidArgumentError("Choose either --json or --html, not both.");
+    }
+    const outputExtension = options.output ? path.extname(options.output).toLowerCase() : "";
+    if (options.json) {
+        if (outputExtension && outputExtension !== ".json") {
+            throw new InvalidArgumentError("--json output files should use a .json extension.");
+        }
+        return "json";
+    }
+    if (options.html) {
+        if (outputExtension && outputExtension !== ".html" && outputExtension !== ".htm") {
+            throw new InvalidArgumentError("--html output files should use a .html extension.");
+        }
+        return "html";
+    }
+    if (outputExtension === ".json") {
+        return "json";
+    }
+    if (outputExtension === ".html" || outputExtension === ".htm") {
+        return "html";
+    }
+    return "terminal";
+}
+function parseOnly(value) {
+    if (value === "production" || value === "development") {
+        return value;
+    }
+    throw new InvalidArgumentError("--only must be either production or development.");
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI5D,MAAM,cAAc,GAAG,OAAO,CAAC;AAY/B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,oBAAoB,CAAC;KAC1B,WAAW,CAAC,8FAA8F,CAAC;KAC3G,OAAO,CAAC,cAAc,CAAC,CAAC;AAE3B,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,6CAA6C,CAAC;KAC1D,MAAM,CAAC,eAAe,EAAE,uBAAuB,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;KAC/D,MAAM,CAAC,QAAQ,EAAE,+BAA+B,CAAC;KACjD,MAAM,CAAC,QAAQ,EAAE,0BAA0B,CAAC;KAC5C,MAAM,CAAC,iBAAiB,EAAE,sCAAsC,CAAC;KACjE,MAAM,CAAC,eAAe,EAAE,kGAAkG,CAAC;KAC3H,MAAM,CAAC,gBAAgB,EAAE,uDAAuD,EAAE,SAAS,CAAC;KAC5F,MAAM,CAAC,aAAa,EAAE,qCAAqC,CAAC;KAC5D,MAAM,CAAC,KAAK,EAAE,OAA2B,EAAE,EAAE;IAC5C,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IACxD,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IACtC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC;AAEH,KAAK,UAAU,OAAO,CAAC,OAA2B;IAChD,MAAM,MAAM,GAAG,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE9C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC;YAC/B,WAAW,EAAE,OAAO,CAAC,IAAI;YACzB,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,UAAU,EAAE,OAAO,CAAC,UAAU;SAC/B,CAAC,CAAC;QAEH,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;gBACnB,MAAM,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;gBAC1C,OAAO;YACT,CAAC;YACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3B,OAAO;QACT,CAAC;QAED,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,IAAI,4BAA4B,CAAC;YAClE,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC,UAAU,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9E,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,WAAW,IAAI,CAAC,CAAC;YAChE,OAAO;QACT,CAAC;QAED,MAAM,cAAc,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;YACxE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8BAA8B,WAAW,IAAI,CAAC,CAAC;YACpE,OAAO;QACT,CAAC;QAED,UAAU,CAAC;YACT,QAAQ,EAAE,OAAO,CAAC,MAAM,KAAK,KAAK;YAClC,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,MAAM,KAAK,UAAU;SAC9B,CAAC,CAAC;QACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;QACjC,CAAC;QACD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,OAA2B;IACxD,IAAI,OAAO,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjC,MAAM,IAAI,oBAAoB,CAAC,2CAA2C,CAAC,CAAC;IAC9E,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEzF,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,eAAe,IAAI,eAAe,KAAK,OAAO,EAAE,CAAC;YACnD,MAAM,IAAI,oBAAoB,CAAC,mDAAmD,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,IAAI,eAAe,IAAI,eAAe,KAAK,OAAO,IAAI,eAAe,KAAK,MAAM,EAAE,CAAC;YACjF,MAAM,IAAI,oBAAoB,CAAC,mDAAmD,CAAC,CAAC;QACtF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,eAAe,KAAK,OAAO,EAAE,CAAC;QAChC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,eAAe,KAAK,OAAO,IAAI,eAAe,KAAK,MAAM,EAAE,CAAC;QAC9D,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,SAAS,CAAC,KAAa;IAC9B,IAAI,KAAK,KAAK,YAAY,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QACtD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,IAAI,oBAAoB,CAAC,kDAAkD,CAAC,CAAC;AACrF,CAAC"}

package/dist/reporters/htmlReporter.d.ts

@@ -0,0 +1,3 @@
+import type { ScanReport } from "../types/index.js";
+export declare function renderHtmlReport(report: ScanReport): string;
+//# sourceMappingURL=htmlReporter.d.ts.map

package/dist/reporters/htmlReporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlReporter.d.ts","sourceRoot":"","sources":["../../src/reporters/htmlReporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiC,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAGnF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAkS3D"}