Introduction
cDoc examines a JavaScript or TypeScript project and reports what needs attention across five areas: project configuration, dependencies, environment variables, git configuration and security. Every finding is graded, and the findings reduce to a single score out of 100.
It runs entirely on your machine. Nothing is uploaded, no account is required, and it never modifies your source files — it only reads them.
Installation
Install the CLI globally:
npm install -g @oluwat0s1n/devdoctorInstalls the CLI globally.
Or run a scan without installing anything:
npx @oluwat0s1n/devdoctor scanOr run a scan without installing anything.
Usage and options
scan is the default command, so these are equivalent:
cdoccdoc scan| Option | What it does |
|---|---|
| --cwd <path> | Scan a directory other than the current one. |
| --json | Emit machine-readable JSON instead of the terminal report. |
| --strict | Exit non-zero on warnings as well as errors — useful in CI. |
| --color | Force ANSI colour on, even when output is piped. |
| --no-color | Force ANSI colour off. |
| -h, --help | Show usage. |
| -v, --version | Show the installed version. |
The five checks
Each check emits individual findings marked as passing, a warning or an error.
Project configuration
Confirms package.json exists and parses, declares name, version, description and license, pins engines.node, defines scripts, and ships a tsconfig.json when TypeScript sources are present.
Dependencies
Requires a lockfile so installs are reproducible, flags any dependency range that pins nothing at all, and catches packages declared in both dependencies and devDependencies.
Environment variables
Confirms local .env files are git-ignored and untracked, and that a committable .env.example documents the required variables. Environment files are never read — only their presence, ignore status and track status.
Git configuration
Checks that a repository exists, that .gitignore covers node_modules and .env, and that no build output or dependencies are tracked.
Security checks
Scans the files git tracks for credential-shaped strings — private keys and AWS, GitHub, Slack, npm, Stripe and Google tokens — and flags any npm script that pipes a download straight into a shell. It prefers git ls-files because that is what actually leaves your machine, and falls back to a filesystem walk when git is unavailable.
Scoring
The scan starts at 100 and deducts points for every finding that is not a pass. The score is floored at 0.
| Severity | Deduction |
|---|---|
| Pass | 0 points |
| Warning | 4 points |
| Error | 12 points |
| Score | Meaning |
|---|---|
| 90–100 | Healthy. |
| 70–89 | Needs attention. |
| 0–69 | At risk. |
Exit codes
Exit codes are designed to be scripted, so CI can gate on a scan without parsing the report.
| Code | Meaning |
|---|---|
| 0 | The scan completed with no errors. |
| 1 | Errors were found — or warnings, when --strict is set. |
| 2 | Invalid usage, such as an unknown option. |
Troubleshooting
“No lockfile found”
Run npm install to generate package-lock.json, or commit the lockfile your package manager already produced.
“TypeScript sources found but no tsconfig.json”
The check searches the whole project, not just the directory you scanned, so a config in a parent folder counts. If nothing is found anywhere, add one with npx tsc --init.
Colour codes appear in my output file
Colour is enabled automatically only when stdout is a terminal. Force it off with --no-color, or set the NO_COLOR environment variable.