DepSignal

Dependency health intelligence for your project — catch risks before they become crises.

Most dependency scanners only flag CVEs. DepSignal goes deeper: it scores your dependencies on signals that predict future risk — maintainer burnout, single-maintainer bus factor, silent ownership transfers, funding collapse, and repository abandonment. By the time a vulnerability is in the NVD database, it's too late. DepSignal helps you act earlier.

Quick Install

npm install -g depsignal

Quick Start

# Scan current project
depsignal scan

# Scan with GitHub signals (much more accurate)
GITHUB_TOKEN=ghp_xxx depsignal scan

# Generate a markdown report
depsignal scan --output markdown --file DEPENDENCY_HEALTH.md

# Use in CI — fail if any package scores below 30
depsignal scan --threshold 30

CLI Reference

depsignal scan

Scan project dependencies and score their health.

Options:
  -p, --path <path>        Path to project (default: current directory)
  -e, --ecosystem <type>   Force ecosystem: npm|pip|go (auto-detected)
  -o, --output <format>    Output format: terminal|json|markdown (default: terminal)
  -f, --file <path>        Save output to file
  --threshold <score>      Exit code 1 if any package below this score
  --only-direct            Only scan direct dependencies
  --min-risk <level>       Only show: critical|high|medium|low|healthy
  --no-cache               Skip cache, force fresh data

depsignal report

Generate a full dependency health report (defaults to markdown output).

depsignal report --output markdown --file DEPENDENCY_HEALTH.md

GitHub Action

Add DepSignal to your CI pipeline to automatically check dependency health on every PR that touches dependency files.

# .github/workflows/dependency-health.yml
name: Dependency Health Check

on:
  pull_request:
    paths:
      - 'package.json'
      - 'package-lock.json'
      - 'requirements.txt'
      - 'go.mod'

jobs:
  dependency-health:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Check dependency health
        uses: arunmm8335/depsignal@v1
        with:
          threshold: '30'
          github-token: ${{ secrets.GITHUB_TOKEN }}

Action Inputs

| Input | Description | Default | |-------|-------------|---------| | threshold | Fail if any package scores below this | 30 | | github-token | GitHub token for API signals | required | | ecosystem | Force ecosystem: npm|pip|go | auto-detect | | path | Path to project | . | | output-file | Save markdown report to this file | — |

The action automatically posts a report as a PR comment and fails the check if the threshold is violated.

How Scoring Works

DepSignal collects signals from GitHub and package registries, then scores each signal on a 0–100 scale. The final score is a weighted sum.

Signals & Weights

| Signal | Weight | What it measures | |--------|--------|-----------------| | Last commit recency | 20% | How recently was the repo actively developed | | Maintainer count | 18% | Bus factor — how many people can publish releases | | Ownership transfer | 15% | Was the package recently transferred to a new owner | | Commit frequency (30d) | 12% | Velocity of active development | | Issue response time | 10% | How responsive are maintainers to bug reports | | Last published | 8% | How recently was a release pushed to the registry | | CI/CD present | 5% | Does the project have automated testing | | Contributor diversity (90d) | 5% | Are multiple people contributing, or just one | | Funding health | 4% | Does the project have sustainable funding | | Download trend | 3% | Is the package growing or declining |

Score Thresholds

| Score | Grade | Risk Level | |-------|-------|-----------| | 85–100 | A | Healthy | | 70–84 | B | Low | | 50–69 | C | Medium | | 30–49 | D | High | | 0–29 | F | Critical |

Hard Overrides

• Archived repository → Score immediately set to 0, flagged critical
• Ownership transfer in last 90 days → Ownership signal score set to 0, critical flag raised
• New maintainer with no contribution history → Ownership signal score set to 10

Configuration

Create a .depsignalrc.json file in your project root:

{
  "threshold": 40,
  "ignorePackages": ["my-internal-package"],
  "onlyDirect": false,
  "failOn": "critical",
  "github": {
    "token": "${GITHUB_TOKEN}"
  },
  "output": {
    "format": "terminal",
    "showHealthy": false
  }
}

DepSignal uses cosmiconfig, so you can also use:

• .depsignalrc.json
• .depsignalrc.yaml
• depsignal.config.js
• "depsignal" key in package.json

Privacy & Data

• DepSignal only reads public registry and GitHub data
• No user data is ever stored or transmitted to any DepSignal server
• Cache is stored locally in ~/.depsignal/cache/ with a 24-hour TTL
• GitHub token is only used for API calls to api.github.com

Without a GitHub Token

DepSignal works without a GitHub token but with reduced accuracy — GitHub signals (commit recency, maintainer count, CI, ownership transfers) will be missing. Add GITHUB_TOKEN to your environment for full signal coverage.

export GITHUB_TOKEN=ghp_yourtoken
depsignal scan

Contributing

1. Fork the repo and clone it
2. Install dependencies: pnpm install
3. Make your changes in src/
4. Run tests: pnpm test
5. Build: pnpm build
6. Submit a PR

Project Structure

src/
  cli/          — Commander.js CLI entry + commands
  parsers/      — Parse package manifests (npm, pip, go)
  collectors/   — Fetch data from GitHub + registries
  scoring/      — Signal calculators + weighted scoring
  output/       — Terminal, JSON, and Markdown renderers
  cache/        — File-based 24hr cache
  types/        — TypeScript interfaces
tests/          — Vitest unit tests

License

MIT © DepSignal Contributors