devmedic

The devmedic executable — a thin orchestration layer over DevMedic's existing engines. It parses arguments, loads configuration, and wires together @devmedic/project-scanner → @devmedic/plugin-sdk → @devmedic/rule-engine → @devmedic/issue-engine → @devmedic/report-engine → @devmedic/autofix-engine. No analysis, fixing, or reporting logic lives here — every command calls the real engine and displays what it returns. Built on Commander, chalk, and ora. See docs/guide.md for the full pipeline and every command's exact wiring.

Commands

| Command | What it does | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | devmedic analyze [path] | Scans, loads plugins, runs every registered rule, and prints a real Report (defaults to colored terminal output) | | devmedic fix [path] | Same analysis, then plans and applies real fixes through the Auto-Fix Engine (--dry-run to preview only) | | devmedic report [path] | The same pipeline, oriented at producing a shareable document (defaults to markdown; --output <file> writes to disk) | | devmedic plugins | Discovers every built-in, workspace, local, configured, and npm plugin, loads each for real, and reports what actually loaded (and what didn't) | | devmedic doctor | Self-diagnostics: Node version, configuration, and whether discovered plugins actually load | | devmedic config | Resolves and prints the effective configuration, and where it came from | | devmedic version | Prints the installed version | | devmedic help | Commander's built-in command listing |

Every analysis-driven command supports --cwd <path> (or a [path] positional argument, which wins if both are given), --json, --format <cli|json|markdown|html|sarif|github-actions-summary>, --verbose, and --ignore <pattern> (repeatable — a real gitignore-syntax pattern, merged with .gitignore/.devmedicignore/workspace/plugin ignores via @devmedic/ignore-engine; applied last, so --ignore '!keep-this.log' can override everything else).

devmedic.config.json's rules map (per-rule severity overrides, e.g. { "console-log": "warning", "unused-dependencies": "off" }) and ignoreRules (shorthand for "off") now actually take effect — wired through @devmedic/severity-engine#createSeverityPolicy into every analysis-driven command, changing both reported Issue severities and the Health Score. See docs/guide.md for the fix and why it was needed.

devmedic fix shares one @devmedic/ast-cache-engine#AstCache between its main analysis pass and its fix pass — a file RuleEngine.analyze() already parsed is a cache hit when attachFixEdits re-parses it to call a rule's real fix(), not a second real parse. See docs/guide.md for the design.

Every plugin now runs through @devmedic/plugin-sdk#validatePlugin — the Plugin Validator — before it's registered: a plugin id or rule id that collides with one already loaded this run is rejected with a diagnostic, not a crash (a duplicate plugin id used to throw uncaught) or a silent no-op (a duplicate rule id used to be swallowed by an unconditional catch {}). See docs/guide.md for both bugs and the fix.

The analysis pipeline is no longer a hidden, monolithic function — it's eleven (analyze/report: thirteen) explicit, named stages, each with its own real timing, metrics, and non-fatal diagnostics. Pass --verbose to any analysis-driven command to see the full breakdown — Project Detection, Plugin Discovery, Plugin Validation, Scanner, Ignore Engine, Severity Engine, Execution Planner, Parser, AST Cache, Rule Engine, Issue Engine, and (for analyze/report) Report Engine, Output Formatter — ending with a total Time. See docs/guide.md for the full stage list, why the real run order deviates from the declared one in three places, and a worked --verbose example.

Error handling & exit codes

resolveConfig failures surface as a CliError with a color-formatted message and the matching exit code; plugin load/lifecycle-hook failures are isolated per plugin (never crash the run) and reported to stderr; anything truly unexpected exits 2 and prints a stack trace only with DEVMEDIC_DEBUG=1 set.

A crashing or hanging rule never stops analysis either — Rule Failure Isolation, in @devmedic/rule-engine. analyze/report render a full "Rule Failures" section (rule, file, phase, reason, stack) in every output format instead of a bare error count with nothing behind it; fix (which doesn't render a Report) prints an ⚠ N rule failure(s) warning to stderr and includes the full ruleFailures/ruleExecutionSummary detail in its --json payload. See @devmedic/rule-engine and @devmedic/report-engine's own READMEs for the full contract.

| Code | Meaning | | ---- | -------------------------------------------------------------------- | | 0 | Clean (all checks passed / no findings / fix applied everything) | | 1 | Findings present, a check failed, or some issues remain unfixed | | 2 | Fatal, unexpected error (including a rolled-back fix transaction) | | 3 | Configuration failed to load/validate, or an unrecognized --format |

Installation

npm install -g devmedic
devmedic analyze

Requires Node.js 20 or later.

Local usage (from a checkout of this monorepo)

pnpm --filter devmedic run build
node apps/cli/dist/index.js analyze
node apps/cli/dist/index.js fix --dry-run
node apps/cli/dist/index.js report --format html --output report.html

Built from (bundled, not published separately)

devmedic is published as a single, self-contained npm package — pnpm run build (scripts/build.mjs) uses esbuild to bundle this CLI together with every internal engine it's built from into one dist/index.js. None of the packages below are published to npm on their own; they exist purely as internal, private workspace packages this repo builds from, listed here as devDependencies (source-level, resolved at build time) rather than dependencies (installed at runtime):

• @devmedic/core
• @devmedic/config
• @devmedic/project-scanner
• @devmedic/project-detection-engine (gates rule execution by project type — see docs/guide.md)
• @devmedic/ignore-engine (merges .gitignore/.devmedicignore/workspace/plugin/CLI ignores for workspace file discovery — see docs/guide.md)
• @devmedic/plugin-sdk
• @devmedic/rule-engine
• @devmedic/ast-cache-engine
• @devmedic/severity-engine
• @devmedic/parser-typescript
• @devmedic/issue-engine
• @devmedic/report-engine
• @devmedic/autofix-engine
• @devmedic/plugin-react-native (the one built-in plugin — see docs/guide.md, "Plugin discovery")

The published package's real dependencies are only genuine third-party npm packages (commander, chalk, ora, the Babel/TypeScript parsing stack, zod, recast, etc.) — installing devmedic never pulls in any @devmedic/* package.