@emirkoksal/devdoctor

DevDoctor

Intelligent error analysis, project diagnostics, and automated fixes for Node.js applications.

DevDoctor analyzes errors, stack traces, project files, environment variables, package versions, and runtime context to identify the real cause of issues and suggest actionable fixes.

---

Features

• Smart Pattern Detection — 65+ built-in error patterns for instant, zero-cost diagnosis
• Comprehensive Health Scores (A-F) — Generates A-F grade cards across Security, Performance, Best Practices, and Configuration
• Proactive Scanners — Scans for exposed secrets, unignored env files, dependency bloat, missing lock files, and lint configuration issues
• AI Analysis — Optional AI layer with multi-provider support (OpenAI, Anthropic, Gemini, Ollama, OpenRouter)
• External Research — Searches GitHub Issues and StackOverflow for similar errors
• Auto-Fix — Automatically resolves common issues with safe, reversible fixes
• Framework Support — Next.js, React, Express, NestJS, Prisma, PostgreSQL, MongoDB, Redis, Docker, TypeScript
• Plugin System — Extensible architecture for custom analyzers, patterns, and providers
• Beautiful CLI — Professional terminal output with grade cards, progress bars, and watch mode
• Local-First — All core features work offline without any API key
• No Telemetry — Zero data collection, fully local operation

---

Installation

npm install devdoctor

---

Quick Start

Library API

import { explain } from 'devdoctor';

try {
  await app.start();
} catch (error) {
  await explain(error);
}

Output:

╭──────────────────────────╮
│ 🩺 DevDoctor Diagnosis   │
╰──────────────────────────╯

Confidence: ██████████ 95%
Source: pattern

❌ Problem Found
Type: TypeError

Cause:
  A variable is undefined but code tries to access property 'name'

Likely Reasons:
  1. Database query returned null/undefined
  2. API response missing expected data
  3. Variable not initialized before use

💡 Suggested Fixes:

  ▸ Add null check before accessing the property
  ┌─────────────
  │ if (!user) {
  │   throw new Error('User not found');
  │ }
  └─────────────

  ▸ Use optional chaining for safe access
  $ const value = obj?.name;

CLI

# Scan current project for issues (Security, Performance, Best Practices)
npx devdoctor scan

# Explain a specific error message or query
npx devdoctor explain "Cannot read properties of undefined"

# Auto-fix detected issues in the workspace
npx devdoctor fix

# Generate a detailed project health report with A-F scores
npx devdoctor health

# Initialize DevDoctor config (devdoctor.config.json) in your project
npx devdoctor init

# Monitor a command and analyze errors in real-time
npx devdoctor watch "npm run dev"

# Dry-run to see what would be fixed
npx devdoctor fix --dry-run

# Output as JSON (for CI/CD)
npx devdoctor scan --json

---

Configuration

DevDoctor can be configured locally using a devdoctor.config.json or .devdoctorrc file in the root of your project.

To initialize a default configuration, run:

npx devdoctor init

Options

{
  // Directories and files to ignore during scans
  "ignore": [
    "node_modules",
    ".git",
    "dist",
    "build",
    ".next",
    "coverage"
  ],
  // Array of check IDs to disable (e.g. "js-unsafe-eval")
  "disabledChecks": [],
  // Minimum severity to report ("info", "warning", "error")
  "minSeverity": "info",
  // Enable or disable specific proactive scanners
  "scanners": {
    "security": true,
    "performance": true,
    "bestPractices": true
  },
  // Optional AI integration configuration
  "ai": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  }
}

---

API Reference

explain(error, config?)

Analyze an error and return a structured diagnosis.

import { explain } from 'devdoctor';

const result = await explain(error, {
  silent: true,           // Don't print to terminal
  enableResearch: true,   // Search GitHub/StackOverflow
  ai: {                   // Optional AI configuration
    provider: 'openai',
    model: 'gpt-4o-mini',
  },
});

console.log(result.rootCause);
console.log(result.confidence);
console.log(result.fixes);

scanProject(path)

Scan a project directory for potential issues.

import { scanProject } from 'devdoctor';

const result = await scanProject('./my-project');
console.log(`Found ${result.issues.length} issues`);
console.log(`Frameworks: ${result.frameworks.join(', ')}`);

getPluginRegistry()

Access the plugin registry to extend DevDoctor.

import { getPluginRegistry } from 'devdoctor';
import type { DevDoctorPlugin } from 'devdoctor';

const plugin: DevDoctorPlugin = {
  metadata: {
    name: 'my-plugin',
    version: '1.0.0',
    description: 'My custom plugin',
  },
  patterns: [/* custom patterns */],
  analyzers: [/* custom framework analyzers */],
};

const registry = getPluginRegistry();
await registry.register(plugin);

---

AI Configuration

AI analysis is entirely optional. All core features work without it.

Set one of these environment variables to enable AI:

Provider	Environment Variable
OpenAI	OPENAI_API_KEY or DEVDOCTOR_OPENAI_KEY
Anthropic	ANTHROPIC_API_KEY or DEVDOCTOR_ANTHROPIC_KEY
Google Gemini	GOOGLE_API_KEY or DEVDOCTOR_GEMINI_KEY
Ollama	DEVDOCTOR_OLLAMA_URL (default: http://localhost:11434)
OpenRouter	OPENROUTER_API_KEY or DEVDOCTOR_OPENROUTER_KEY

DevDoctor auto-detects the first available provider.

---

Plugin System

Create custom plugins to extend DevDoctor with:

• Error patterns — Custom regex-based pattern matching
• Framework analyzers — Project scanning for custom frameworks
• AI providers — Custom AI backends
• Research providers — Custom external search sources
• Auto-fixers — Custom automatic fixes

See examples/plugin-example.ts for a complete plugin example.

---

Supported Frameworks

Framework	Error Patterns	Project Scanning
Next.js	Hydration, server components, dynamic usage	Config, env vars, Docker
React	Hooks, key props	Version mismatch, JSX config
Express	Headers sent, view engine	CORS, Helmet, rate limiting
NestJS	Circular deps, DI errors	reflect-metadata, validation
Prisma	Client init, unique constraint, P2025	DATABASE_URL, schema, generate
PostgreSQL	Connection errors	Connection string, pooling
MongoDB	Connection, selection errors	URI config, placeholder detection
Redis	Connection, auth errors	URL config
Docker	Networking, localhost issues	.dockerignore, image size, multi-stage
TypeScript	Declaration files, ESM/CJS	strict mode, module resolution

---

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Build
npm run build

# Lint
npm run lint

# Type check
npm run typecheck

---

Architecture

src/
├── index.ts                    # Public API
├── types/index.ts              # All TypeScript interfaces
├── utils/                      # Error parser, file reader, version utils
├── patterns/                   # Local error pattern matching
├── ai/                         # AI provider abstraction
│   └── providers/              # OpenAI, Anthropic, Gemini, Ollama, OpenRouter
├── research/                   # GitHub Issues, StackOverflow search
├── frameworks/                 # Framework-specific analyzers
├── analyzers/                  # Core analysis pipeline
├── reporters/                  # Terminal and JSON output
├── fixers/                     # Auto-fix system
├── plugins/                    # Plugin registry
└── cli/                        # CLI entry point and commands

Analysis Pipeline

Error → Parse → Pattern Match → Framework Analysis → External Research → AI → Report
                  (local)         (local)              (optional)        (optional)

---

Privacy & Security

• No telemetry — DevDoctor collects zero usage data
• Local-first — All pattern matching and project scanning runs locally
• AI is optional — External API calls only happen when AI is explicitly configured
• No data stored — Error data is never persisted or transmitted (except to your configured AI provider)

---

License

MIT