Hemanth

Posted on May 1

I Built a Zero-Config Project Health Analyzer — Just Run npx dev-lens in Any Repo

#opensource #node #cli #devtools

The Problem

Every time I open an unfamiliar codebase, I run the same ritual:

cloc .                  # how big is this thing?
git shortlog -sn        # who wrote it?
npm outdated            # how stale are the deps?
grep -r "TODO" src/     # how much debt is hiding?

Four commands. Four different output formats. Mental math to combine them.

I got tired of it — so I built dev-lens.

What is dev-lens?

dev-lens is a zero-config CLI that runs in any project directory and gives you a full health report in seconds.

npx dev-lens

No install. No config file. No setup. Just run it.

What It Shows You

📁 Code Overview

Total files and lines of code
Language breakdown with visual bar chart
Top 5 largest files

🌿 Git Health

Current branch + working directory status
Total commits + commits in last 30 days
Top contributors with commit counts
Last commit: hash, message, author, time ago

📦 Dependencies

Ecosystem auto-detection (Node, Python, Rust, Go, Ruby)
Total production + dev dependency count
Outdated packages with current → latest versions

🐛 Technical Debt

Scans every source file for TODO / FIXME / BUG / HACK / XXX
Shows file path + line number for each item
Sorted by priority (BUG first, NOTE last)

❤️ Health Score

Weighted 0–100 score with A–F letter grade
Penalties for: stale commits, outdated deps, open bugs

Example Output

╭──────────────────────────────────────────────────╮
│  🔍 dev-lens v1.0.0                              │
│                                                  │
│  Project: my-saas-app                            │
│  Health:    88/100 (B+)                          │
│  ✓ All good                                      │
╰──────────────────────────────────────────────────╯

  ◆ CODE OVERVIEW
  Files        342
  Lines        28.4K
  Primary      TypeScript

  TypeScript   61%  ▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░  186f
  CSS          14%  ▓▓▓░░░░░░░░░░░░░░░   28f
  JSON          9%  ▓▓░░░░░░░░░░░░░░░░   61f

  ◆ GIT HEALTH
  Branch       main  ✓ clean
  Commits      1.2K total, 47 last 30d

  Alice Chen   ▓▓▓▓▓▓▓▓▓▓▓▓  312
  Bob Smith    ▓▓▓▓▓▓▓░░░░░  201

  ◆ DEPENDENCIES
  Total        64  ✓ All packages up to date

  ◆ TODOS & TECHNICAL DEBT
  FIXME        4
  HACK         3
  TODO         14

CLI Options

npx dev-lens                        # current directory
npx dev-lens --path /any/project    # specific path
npx dev-lens --json                 # machine-readable output
npx dev-lens --no-git               # skip git analysis
npx dev-lens --no-deps              # skip dependency check

Use It in CI

- name: Project Health Check
  run: npx dev-lens --json > health.json

Pipe the JSON into any monitoring system, Slack bot, or dashboard.

How I Built It (with Claude)

I built dev-lens using Claude as my AI coding assistant. The parts where it helped most:

Designing the multi-ecosystem dependency parser (Node/Python/Rust/Go in one file)
Writing the regex pattern for the TODO scanner that handles //, #, /* */, and  comment styles
Building the terminal color theme using chalk with a consistent palette
Writing Jest tests that run the analyzer on the project itself

The whole project is ~700 lines of clean JavaScript.

What's Next

[ ] HTML/PDF report export
[ ] --watch mode
[ ] Outdated dep check for Python, Rust, Go
[ ] Historical tracking (compare health over time)
[ ] .devlens.json config for custom ignore patterns

Try It

npx dev-lens

GitHub (MIT licensed): https://github.com/CHHemant/dev-lens

Built by Hemant Chilkuri — feedback and PRs very welcome. What metrics would you want to see added?

DEV Community