dormant-maintainer-audit

Audit npm dependencies for stale maintainers, zombie packages, and maintenance risk.

A production-ready TypeScript library and CLI that analyzes your package.json dependencies and generates a Health & Risk Report. Flags dependencies based on publish recency (staleness) and maintainer concentration (bus factor).

Features

• Stale-Maintainer Score — Days since last npm publish, classified into four risk levels
• Bus Factor Risk — Number of npm maintainers and contributor concentration signals
• Confidence Scoring — Transparency about data completeness for each dependency
• Human & Machine Output — Colorized CLI table or JSON for CI pipelines
• Configurable Thresholds — Customize staleness windows per your policy
• Zero Heavy Dependencies — Uses native fetch, minimal runtime deps (commander + cli-table3)
• TypeScript First — Full type declarations, dual ESM/CJS output

Installation

# Use directly via npx (no install required)
npx dormant-maintainer-audit

# Or install globally
npm install -g dormant-maintainer-audit

# Or add as a dev dependency
npm install --save-dev dormant-maintainer-audit

CLI Usage

# Analyze current project
npx dormant-maintainer-audit

# Analyze a specific package.json
npx dormant-maintainer-audit --path ./path/to/package.json

# JSON output for CI pipelines
npx dormant-maintainer-audit --json

# Ignore specific packages
npx dormant-maintainer-audit --ignore lodash,axios

# Custom staleness thresholds (m = months, y = years, d = days)
npx dormant-maintainer-audit --threshold healthy=6m,monitor=12m,stale=24m

# Write report to file
npx dormant-maintainer-audit --output report.json

# Exit non-zero if risky or zombie packages found
npx dormant-maintainer-audit --exit-on-risky

API Usage

import { analyzePackageJson } from 'dormant-maintainer-audit';

// Analyze your project's package.json
const report = await analyzePackageJson({
  path: './package.json',
  ignore: ['lodash'],
  thresholds: {
    healthyMaxDays: 90,
    monitorMaxDays: 180,
    riskyMaxDays: 365,
  },
});

console.log(`Analyzed ${report.packageCount} packages`);
console.log(`Risky: ${report.summary.risky}, Zombie: ${report.summary.zombieCandidate}`);

Programmatic API

| Function | Description | |----------|-------------| | analyzePackageJson(options?) | Reads and analyzes a project's package.json | | analyzeDependencies(deps, options?) | Analyzes a dependency map directly | | generateReport(analyses, thresholds) | Builds a Report from pre-computed analyses | | formatCliReport(report) | Returns a colorized CLI table string | | formatJsonReport(report) | Returns a JSON string | | writeJsonReport(report, path) | Returns JSON (use with fs.writeFileSync) |

Types

interface DependencyAnalysis {
  name: string;
  requestedVersion: string;
  requestedVersionPublishDate: string | null;  // When the installed version was published
  latestVersion: string | null;
  lastPublishDate: string | null;               // When the latest version was published
  daysSinceUpdate: number | null;
  stalenessScore: number;           // 0 | 25 | 50 | 75
  stalenessLevel: RiskLevel;
  stalenessExplanation: string;
  busFactorRisk: BusFactorRisk;     // 'low' | 'medium' | 'high' | 'unknown'
  busFactorScore: number;           // 0 | 35 | 50 | 75
  busFactorExplanation: string;
  maintainerCount: number | null;
  confidence: ConfidenceLevel;      // 'high' | 'medium' | 'low'
  confidenceExplanation: string;
  classification: RiskLevel;        // Final risk level
}

Scoring Model

Staleness (based on days since last npm publish)

| Range | Score | Level | |-------|-------|-------| | 0 – 180 days | 0 | Healthy | | 181 – 365 days | 25 | Monitor | | 366 – 730 days | 50 | Risky | | > 730 days | 75 | Zombie Candidate |

Bus Factor (based on npm maintainer count)

| Maintainers | Score | Risk | |-------------|-------|------| | 0 (no data) | 50 | Unknown | | 1 | 75 | High | | 2 – 3 | 35 | Medium | | 4+ | 0 | Low |

Confidence

| Data Available | Level | |----------------|-------| | Both publish date + maintainers | High | | Either publish date or maintainers | Medium | | Neither | Low |

Overall Classification

The final classification is driven by the staleness level. Bus factor is a supplementary risk indicator shown in the report.

Default Thresholds

{
  healthyMaxDays: 180,   // 0-180 days → healthy
  monitorMaxDays: 365,   // 181-365 days → monitor
  riskyMaxDays: 730,     // 366-730 days → risky
                         // >730 days → zombie-candidate
}

Project Structure

src/
├── cli/          # CLI entry point (commander)
├── config/       # Defaults and validation
├── registry/     # npm registry API fetcher
├── repository/   # GitHub metadata fetcher (optional)
├── reporting/    # CLI table + JSON output formatters
├── scoring/      # Staleness + Bus Factor computation
├── types/        # TypeScript interfaces and schemas
└── utils/        # Date helpers, logging, package.json reader

Requirements

• Node.js 18+ (native fetch support)

License

MIT