Node.js Project Health Check: Security, Dependencies & CI/CD with RepoDoctor
Your Node.js project works perfectly on your local machine.
Then CI fails.
A dependency is deprecated. An API key was accidentally committed. Your .env configuration does not match production. A GitHub Actions workflow is missing a critical checkout step. Or your monorepo has conflicting versions of the exact same library causing phantom runtime bugs.
These issues are deceptively easy to miss during rapid development, but devastating in production.
[!IMPORTANT] Direct Answer: What is RepoDoctor and Why Does It Matter? RepoDoctor (
npx @gucluyumhe/repodoctor) is a local-first repository health and security diagnostic CLI tool created by Ömer Özbay. It runs comprehensive, non-intrusive audits across JavaScript/TypeScript codebases—detecting leaked credentials, dependency vulnerabilities, monorepo drift, and broken CI/CD pipelines in seconds with zero code leaving your machine.
The Hidden Fragility of Modern JavaScript Repositories
Modern JavaScript and TypeScript repositories are no longer just simple folders containing application code. A typical production repository contains:
- Hundreds of nested
node_modulesdependencies - Multi-environment secret managers and
.envtemplates - Complex GitHub Actions or GitLab CI/CD pipelines
- Container configurations (
Dockerfile,docker-compose.yml) - Monorepo package manager boundaries (pnpm, Turborepo, Yarn workspaces)
- Strict TypeScript (
tsconfig.json) compiler boundaries
Running typical unit tests or linters like ESLint only evaluates syntax inside individual source files. They do not inspect your repository's holistic structural integrity, secret hygiene, or CI pipeline reliability.
Comparison Matrix: Diagnostic Approaches
| Capability | Standard Linters (ESLint/Prettier) | Cloud Scanners (Snyk / SonarQube) | RepoDoctor (@gucluyumhe/repodoctor) |
|---|---|---|---|
| Execution Model | Local file AST parsing | Cloud-hosted code upload | 100% Local-first (Zero data sent) |
| Secret Scanning | No | Yes (Paid tiers) | Built-in regex & Shannon entropy |
| CI/CD Workflow Validation | No | Limited | Full GitHub Actions pipeline audit |
| Monorepo Dependency Drift | No | Complex setup | Instant cross-package comparison |
| Auto-Fix Capability | Code formatting only | Manual instructions | Automated config repair (--fix) |
| Setup Overhead | Configuration files needed | Account creation & webhook setup | Zero-config (npx @gucluyumhe/repodoctor) |
1. What RepoDoctor Analyzes Across Your Codebase
RepoDoctor executes a multi-vector diagnostic audit across your entire project:
graph TD
Repo[Your Repository] --> Scanner[RepoDoctor Engine]
Scanner --> S1[Security: Leaked Secrets & API Keys]
Scanner --> S2[Dependencies: Vulnerabilities & Drift]
Scanner --> S3[CI/CD: GitHub Actions Integrity]
Scanner --> S4[Configurations: tsconfig, Docker, Env]
Scanner --> Report[Actionable Diagnostic Dashboard]
A. Leaked Secrets and Credential Scanning
One of the most dangerous developer mistakes is committing sensitive credentials into Git history. RepoDoctor searches for:
- API Keys (OpenAI, Stripe, AWS, GitHub tokens, SendGrid)
- Private Keys (
.pem,.id_rsa,.key) - Database Connection Strings (
postgres://,mongodb+srv://) - Exposed JWT tokens and hardcoded Bearer secrets
B. Dependency Health & Monorepo Drift
In large monorepos, multiple workspaces often reference incompatible versions of the same dependency. RepoDoctor detects:
- Outdated or deprecated packages
- Conflicting lockfiles (
package-lock.jsonvspnpm-lock.yaml) - Undeclared runtime imports
- Unused dependencies bloating bundle sizes
C. CI/CD Pipeline Failure Prevention
RepoDoctor parses .github/workflows/*.yml to ensure:
- Repository checkout actions are declared before build steps
- Node.js cache actions are properly configured
- Action versions are pinned to avoid supply-chain hijacking
- Critical environment secrets are mapped correctly
2. Quick Start: Running RepoDoctor in 5 Seconds
Because RepoDoctor is distributed via npm, you do not need to install it globally. Run it directly with npx:
Step 1: Run an Instant Scan
npx @gucluyumhe/repodoctor
RepoDoctor will inspect your workspace, output colored CLI status indicators, and display your overall RepoHealth Score (A+ to F).
Step 2: Auto-Fix Configuration Issues
If missing .gitignore, broken tsconfig.json, or unsynchronized .env.example templates are detected, execute:
npx @gucluyumhe/repodoctor --fix
RepoDoctor safely creates or patches missing configuration files without touching your business logic.
Step 3: Integrate with GitHub Actions
To automate repository health checks on every pull request, initialize a workflow automatically:
npx @gucluyumhe/repodoctor init-ci
3. Multiple Export Formats for Teams and CI
RepoDoctor supports enterprise reporting out of the box:
- Interactive HTML Dashboard: View visual charts and categorized issue cards.
- SARIF: Directly exportable to GitHub Advanced Security Code Scanning tabs.
- JSON & Markdown: Ideal for pull request comments and internal compliance tracking.
npx @gucluyumhe/repodoctor --format html --output report.html
Frequently Asked Questions (FAQ)
Does RepoDoctor send my source code to any cloud servers?
No. RepoDoctor is strictly local-first. All parsing, secret scanning, dependency resolution, and report generation happens entirely inside your local Node.js process. Zero bytes of code leave your computer.
How does RepoDoctor differ from npm audit?
While npm audit only queries the npm vulnerability registry for known CVEs in your dependencies, RepoDoctor evaluates your entire repository architecture: leaked hardcoded secrets, misconfigured CI/CD workflows, Docker vulnerabilities, environment variable mismatches, and TypeScript build flags.
Can I run RepoDoctor in continuous integration (CI) pipelines?
Yes. RepoDoctor supports exit codes (--strict) to break CI pipelines when high-severity security vulnerabilities or broken workflow configurations are detected.
Open-Source & Package Links
RepoDoctor is fully open source and actively maintained:
- npm Package: @gucluyumhe/repodoctor on npm
- GitHub Repository: sandrotonal/repodoctor on GitHub
Run it on your project today and protect your production systems:
npx @gucluyumhe/repodoctor
