Skip to content

prow57/depdoctor

BranchesTags

Repository files navigation

CodeSucks / DepDoctor

Intelligent Dependency Resolution & Optimization Platform

DepDoctor scans your projects, finds dependency problems (conflicts, deprecations, vulnerabilities, unmaintained packages), explains them in plain English, recommends modern alternatives, and applies safe automatic fixes — from the CLI, inside VS Code, in your CI pipeline, or via a future web dashboard, all powered by the same shared core.

Currently supports Node.js, React Native, and Flutter projects.

For a task-focused walkthrough, see the full User Guide.

$ depdoctor scan ./fixtures/messy-project

  DepDoctor · dependency diagnosis

╭────────────────────────────────────────────────────────────╮
│ Project        messy-project @0.0.1                        │
│ Ecosystem      Node.js                                     │
│ Dependencies   …                                           │
│ Health score   ████████░░  …/100                           │
│ Issues         HIGH … │ MEDIUM …                           │
│ Advisories     …                                           │
╰────────────────────────────────────────────────────────────╯

╭─ HIGH · deprecated ────────────────────────────────────────
│ ▶ "request" is deprecated
│ AI · template
│   …plain-language explanation…
│ Actions
│   …what to do next…
│ Alternatives
│   • axios — …
│ Suggested fixes
│   [risky] Replace "request" with a maintained alternative
│     $ npm uninstall request
╰────────────────────────────────────────────────────────────╯

Status

Phase Scope Status
1 Core engine + Node.js CLI + VS Code ext. ✅ Done
2 Flutter + React Native scanners + pub.dev ✅ Done
3 OpenAI / Ollama AI providers ✅ Done
4 GitHub Action (PR comments + Job Summary) ✅ Done
5 Web dashboard (team analytics) ✅ Done
6 Vulnerability DB integration (OSV.dev) ✅ Done

Supported ecosystems

Ecosystem Manifest Lock file Registry Package manager (for fixes)
Node.js package.json package-lock.json / pnpm-lock.yaml / yarn.lock npm registry npm / pnpm / yarn (auto-detected)
React Native package.json (+ ios/Podfile, android/build.gradle for native detection) same as Node npm registry npm / pnpm / yarn (auto-detected)
Flutter pubspec.yaml pubspec.lock pub.dev flutter pub

Quick start

pnpm install
pnpm build
pnpm test:run

# scan a project
node packages/cli/dist/cli.js scan ./path/to/project

# offline (no registry calls)
node packages/cli/dist/cli.js scan ./path/to/project --offline

# JSON output for CI (mutually exclusive with interactive mode)
node packages/cli/dist/cli.js scan ./path/to/project --json

# AI-backed explanations (see environment variables below)
node packages/cli/dist/cli.js scan ./path/to/project --explain-with openai
node packages/cli/dist/cli.js scan ./path/to/project --explain-with ollama

# post-scan menu (inspect issues, safe fixes, full report) — requires a TTY
node packages/cli/dist/cli.js scan ./path/to/project --interactive

AI explanations (template · OpenAI · Ollama)

By default the CLI uses built-in template explanations (no API keys). For richer wording you can call OpenAI-compatible chat completions or a local Ollama model:

Flag / env Purpose
--explain-with (template · openai · ollama) Backend selection (default template; alias env DEPDOCTOR_EXPLAIN_WITH)
OPENAI_API_KEY Required for --explain-with openai
OPENAI_MODEL, OPENAI_BASE_URL Optional model and base URL (custom gateways)
OLLAMA_HOST or OLLAMA_BASE_URL, OLLAMA_MODEL Ollama server and model for --explain-with ollama

Interactive mode (-i / --interactive) opens a small menu after the scan so you can drill into issues, browse package health, apply safe fixes only, or dump the full text report.

Three demo projects ship in fixtures/:

# Node.js — deprecated request, version conflict on react, peer mismatch
node packages/cli/dist/cli.js scan fixtures/messy-project

# React Native — RN 0.72 paired with React 17 (incompatible)
node packages/cli/dist/cli.js scan fixtures/messy-rn-project

# Flutter — pre-null-safety SDK constraint, discontinued packages from pub.dev
node packages/cli/dist/cli.js scan fixtures/messy-flutter-project

Architecture

[ CLI / VS Code / CI / Web ]
              ↓
  ┌────────────────────────────┐
  │   @codesucks/core          │
  │  ┌──────────────────────┐  │
  │  │ Project Scanner      │  │ ← multi-ecosystem adapters (Node first)
  │  ├──────────────────────┤  │
  │  │ Dependency Graph     │  │ ← duplicates, conflicts, transitive
  │  ├──────────────────────┤  │
  │  │ Package Intelligence │  │ ← npm registry + health scoring
  │  ├──────────────────────┤  │
  │  │ Issue Detection      │  │ ← rule engine (pluggable)
  │  ├──────────────────────┤  │
  │  │ Alternatives         │  │ ← curated catalog + ranking
  │  ├──────────────────────┤  │
  │  │ AI Explanation       │  │ ← template · OpenAI · Ollama providers
  │  ├──────────────────────┤  │
  │  │ Fix Engine           │  │ ← safe / semi-safe / risky tiers
  │  └──────────────────────┘  │
  └────────────────────────────┘

Each engine is independently importable, replaceable, and testable. The CLI, the VS Code extension, the upcoming GitHub Action, and the future web dashboard all consume the same @codesucks/core API — that's how we keep them in lockstep.

Repository layout

packages/
  core/              # @codesucks/core — engines, types, pipeline orchestrator
  cli/               # @codesucks/cli — `depdoctor` / `codesucks` binary
  vscode-extension/  # codesucks-vscode — diagnostics, code-actions, panel
  github-action/     # @codesucks/github-action — CI gate, PR comments, Job Summary
  web-server/        # @codesucks/web-server — ingestion API + SPA host (Hono + SQLite)
  web-app/           # @codesucks/web-app — team-analytics dashboard (Vite + React)
fixtures/
  messy-project/         # Node.js fixture
  messy-rn-project/      # React Native fixture
  messy-flutter-project/ # Flutter fixture
.github/workflows/
  depdoctor.yml      # example workflow that calls the action

CI usage (GitHub Action)

permissions:
  contents: read
  pull-requests: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - id: depdoctor
        uses: ./packages/github-action # or codesucks/depdoctor-action@v0
        with:
          path: "."
          fail-on: "high"

The action posts a sticky PR comment, writes a markdown Job Summary, sets step outputs (score, issues-count, severity counts), and fails the job when issues at or above fail-on are detected. See packages/github-action/README.md.

Add upload-to: (and optionally organization:) to stream every CI scan into your team dashboard:

      - uses: ./packages/github-action
        with:
          upload-to: https://depdoctor.acme.com
          organization: platform-team
          upload-api-key: ${{ secrets.DEPDOCTOR_TOKEN }}

Security advisories (OSV.dev)

Every scan automatically queries OSV.dev for known security advisories that affect the resolved versions of your dependencies. Findings are surfaced as vulnerability issues — the same shape as every other DepDoctor issue — so they flow through the CLI, VS Code, the GitHub Action, and the web dashboard without any extra configuration.

$ depdoctor scan ./fixtures/messy-project
📦 DepDoctor scan
project messy-project@0.0.1
ecosystem Node.js
score 0/100
vulnerabilities 23 known across 3 packages

✗ "lodash" has a known vulnerability (CVE-2026-4800) [vulnerability · high]
  lodash vulnerable to Code Injection via `_.template`. Patched in lodash@4.18.0 or later.
  CVE-2026-4800 · https://nvd.nist.gov/vuln/detail/CVE-2026-4800
  ➜ Run `npm install lodash@4.18.0` and re-run the lock file.
  Suggested fixes:
    [semi-safe] Upgrade "lodash" to 4.18.0 to patch GHSA-r5fr-rjxr-66jc (CVE-2026-4800)
      $ npm install lodash@4.18.0

What you get:

  • CVE / GHSA ids as aliases on every advisory.
  • CVSS v3 score parsed from the OSV record (mapped to low | medium | high | critical).
  • Patched version extracted from the affected ranges, surfaced in the issue metadata and used by the upgrade-to-safe fix strategy to generate exact npm install pkg@<patched-version> (or flutter pub add) commands.
  • Batched lookups — a single OSV querybatch round-trip per scan, with in-memory caching for repeated lookups.
  • Coverage: npm (Node.js + React Native) and Pub (Flutter) via the same composite provider.

Disable the network lookup with --offline (skips intelligence + advisories) or --no-vulnerabilities (keeps registry intelligence but skips OSV). The GitHub Action does the same automatically when offline: true is set.

Web dashboard (team analytics)

The dashboard is two packages working together:

# build & start the server (also serves the SPA at /)
pnpm --filter @codesucks/web-app build
pnpm --filter @codesucks/web-server build
PORT=4000 node packages/web-server/dist/index.js

Then upload reports from the CLI:

node packages/cli/dist/cli.js scan ./my-project \
  --upload-to http://localhost:4000 \
  --organization platform-team

…or have the GitHub Action push them on every PR (see snippet above). On http://localhost:4000 you get:

  • KPIs: project count, reports ingested, average latest score, riskiest project.
  • Project grid with health badges and last-scan timestamps per ecosystem.
  • Top risky packages ranked by how many of your projects they appear in.
  • Project detail page with a 30-point score trend, severity counts, rendered issues, alternatives, AI explanations, and runnable fix command blocks.
  • Drag-and-drop uploader for offline / one-off reports.

Set DEPDOCTOR_API_KEY on the server to require Authorization: Bearer … on uploads, then pass the same key as --api-key (CLI) or upload-api-key (Action).

Scripts

Command What it does
pnpm build Build every package (tsup → dist/)
pnpm dev Watch-mode build for every package
pnpm test Vitest in watch mode
pnpm test:run Vitest single run
pnpm typecheck Builds @codesucks/core first (for .d.ts), then TypeScript checks every package
pnpm clean Remove every dist/ directory
pnpm cli Run the CLI from the workspace

Detection rules

Rule Ecosystems Severity What it catches
vulnerability all mapped from CVSS (low → critical) Known security advisories from OSV.dev (CVE/GHSA), with ranges + patched versions
version-conflict all high (cross-major) / low Same package at multiple major versions
duplicate all low Same-major dupes worth deduplicating
peer-dependency Node, RN medium Missing or unsatisfied declared peer dependencies
deprecated all high Packages flagged deprecated by the registry
unmaintained all medium No releases in ~18+ months
lock-inconsistency all medium Lock file resolves outside the manifest range
flutter-sdk-constraint Flutter low / medium / critical Missing, pre-null-safety, or unbounded Dart SDK range
react-native-compat React Native high RN ⇄ React version mismatch, or critically old RN

Rules are plain modules (packages/core/src/detection/rules/*.ts) — adding new ones is a single export.

Fix tiers

Risk Behaviour
safe Idempotent, reversible (cache clean, regenerate lock, dedupe). Auto-applicable.
semi-safe May change versions / install new deps. Requires --yes.
risky Removes or replaces packages. Always prompts for confirmation.

The CLI defaults to applying only safe fixes; the VS Code extension always asks for confirmation before running anything risky.

License

MIT License

Copyright (c) 2026, Immanuel Bester (Github - Prow57)

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.

About

I'm building this because codesucks and i can't be spending the time fixing dependencies everytime

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages