First run is scan (full applicable diagnosis). Then --changed or --quick to narrow.
Method
Scan, measure, prescribe, verify.
VibeDoctor is a diagnosis layer, not a single linter. It detects the repository, builds shared context, runs applicable engines and native detectors, analyzes flows, correlates evidence, ranks root causes, and produces a report. A missing check is never a silent pass.
npx @neuralaxis/vibedoctor scan Loop
The same four steps, every time.
Read completeness.status, the coverage table, and ranked findings.
agent-plan, explain <id>, optional fix --safe.
verify re-runs a changed-scope scan. Review every generated edit.
Scan modes
First run is scan. Narrow later.
| Goal | Command |
|---|---|
| First diagnosis, or before you ship | npx @neuralaxis/vibedoctor scan |
| Fast repository check | npx @neuralaxis/vibedoctor scan --quick |
| Files changed in Git after a baseline | npx @neuralaxis/vibedoctor scan --changed |
| Selected categories | scan --category dead_code,leftovers |
| Fresh full report | report --json | --html | --markdown | --sarif | --agent |
Evidence
Completeness is a first-class result.
COMPLETE
All required checks completed.
Work through the ranked findings.
PARTIAL
Some checks were skipped, failed, or timed out.
Follow recoveryActions. Do not rely on the score alone.
INVALID
Not enough trustworthy evidence for an authoritative result.
Recover the required scanners and scan again before editing.
| Exit | Meaning |
|---|---|
| 0 | The scan completed and configured gates passed. |
| 1 | One or more configured health gates failed. |
| 2 | Required checks were incomplete. |
Tool states: completed · partial · timed out · failed · not installed · runtime mismatch · deferred · disabled · not applicable · not selected. Only completed is full coverage.
Finding grades
Severity is not the same as evidence.
A naming guess must not read like a traced code path. Each finding can carry an evidence grade independent of how bad the claim would be if true.
verified
A code path was followed and the claim holds.
observed
A concrete match exists at a real location; its meaning is inferred.
heuristic
Inferred from names, patterns, or shape rather than behaviour.
unproven
Neither presence nor absence could be established from the code.
Language matrix
What applies where.
Cells are the tools VibeDoctor actually wires for that language. Mixed repositories get the union of applicable rows. A dash means no dedicated tool.
| Check | JavaScript | TypeScript | Python |
|---|---|---|---|
| Leftovers / AI residue | built-in | built-in | built-in |
| Dead code | knip | knip | vulture |
| Types | — | tsc | pyright |
| Lint | biome | biome | ruff |
| Tests | vitest / jest | vitest / jest | coverage.py |
| Dependencies | knip | knip | deptry |
| Duplication | jscpd | jscpd | — |
| Complexity | lizard | lizard | radon / lizard |
| Secrets | gitleaks | gitleaks | gitleaks |
| Known vulns | osv-scanner | osv-scanner | osv-scanner |
| Security rules | semgrep | semgrep | semgrep |
| Privacy signals | privacy-detector | privacy-detector | privacy-detector |
| Optional PII analyzer | presidio | presidio | presidio |
| Refactor size | custom-refactor | custom-refactor | custom-refactor |
| Telemetry opt-out | telemetry-detector | telemetry-detector | — |
| Flow contracts (V1) | flow-doctor | flow-doctor | flow-doctor |
Orchestration
Specialist tools, one record format.
- 01 Detect repo
Read the tree: language, lockfiles, configs. Decide which capabilities apply.
- 02 Build shared context
Index files, git delta, file roles, and the tool runtime. Later graphs attach here.
- 03 Run applicable engines
Native detectors plus engines such as Ruff or Semgrep. Irrelevant tools are NOT_APPLICABLE, not failures.
- 04 Analyze flows
Flow Doctor binds routes to handlers and flags missing wiring plus high-confidence unreachable handlers. Dynamic paths stay heuristic.
- 05 Correlate evidence
Overlapping scanner output becomes one diagnosis, not five unrelated warnings.
- 06 Rank root causes
Real bugs and secrets outrank unused-import noise. Completeness stays a first-class result.
- 07 Produce the report
A prioritized report a human or coding agent can act on immediately.
VibeDoctor owns detection, context, correlation, ranking, completeness, and Flow Doctor. Ruff, Semgrep, Gitleaks, and the other engines remain analysis engines behind that layer — they are not the product.
Built-in detectors always apply. External tools run when they are applicable and resolvable. A missing optional tool is disclosed, not imagined as a pass.
| Tool | Ecosystem | Languages | Role |
|---|---|---|---|
| custom-leftovers | built-in | any | Stale TODOs, commented-out code, fallbacks, AI leftovers. |
| custom-dead-chain | built-in | any | Isolated file clusters after external dead-code tools report candidates. |
| custom-refactor | built-in | any | Large or complex files that need tests before refactor work. |
| privacy-detector | built-in | any | Personal-data and Privacy Review signals. Stays on the machine. |
| telemetry-detector | built-in | JS / TS | Optional telemetry opt-out signal for frameworks that collect it. |
| flow-doctor | built-in | JS / TS / Python | Structural flow checks: route/handler wiring, swallowed errors, high-confidence unreachable handlers. |
| tsc | npm | TypeScript | TypeScript correctness. |
| biome | npm | JS / TS | Lint and safe formatting. |
| knip | npm | JS / TS | Unused files, exports, and dependencies. |
| jscpd | npm | JS / TS | Duplication for refactor planning. |
| ruff | python | Python | Lint and safe-fix signal. |
| pyright | python | Python | Type correctness. |
| vulture | python | Python | Dead-code signal. |
| deptry | python | Python | Dependency hygiene. |
| radon | python | Python | Complexity. |
| coverage.py | python | Python | Coverage. |
| gitleaks | managed | any | Secret detection. VibeDoctor can provision a pinned copy. |
| osv-scanner | managed | any | Known-vulnerability detection from lockfiles. VibeDoctor can provision a pinned copy. |
| semgrep | manual | any | Additional security and correctness rules. |
| lizard | manual | any | Function-level complexity and size. |
| presidio | manual | any | Optional external PII analyzer. Skipped if missing. |
| vitest / jest | npm | JS / TS | Test failure signal. |
Readability
Nothing is dropped silently.
Ranking
New findings and findings in changed files first. Pre-existing debt does not hide a regression.
Per-tool caps
What falls outside the cap is reported as a count, with the setting to raise.
File roles
Tests, fixtures, generated, and vendored code are downgraded rather than presented like production defects.
Acknowledgements
.vibedoctor/suppressions.yml requires a reason. Lapsed rules resurface instead of staying hidden.
Setup
Install what you intend to trust.
npx @neuralaxis/vibedoctor setup setup --apply installs supported recommended tools, then verifies
each one the way the scanner will. It fails if a tool cannot be verified —
even when the install command itself succeeded.
Timed-out tools can be retried: npx @neuralaxis/vibedoctor tool retry semgrep --timeout 600
Specimen coverage row for this idea: semgrep timed out.
Then run the diagnosis you came for:
npx @neuralaxis/vibedoctor scan --full