Dr. Huatuo

Code Quality Diagnosis Toolkit

5-dimension quality profiling for Python and TypeScript. Named after the legendary physician Hua Tuo (华佗) — it diagnoses code health.

What is dr-huatuo?

dr-huatuo orchestrates static analysis tools into a unified quality profile with 5 independent dimensions. No single aggregate score — each dimension gets its own grade so you know exactly what to fix.

• Multi-Language — Python (ruff, radon, bandit, mypy, pylint, complexipy) and TypeScript (eslint, tsc, escomplex)
• 5-Dimension Quality Profile — Maintainability, Complexity, Code Style, Documentation, Security
• CI Quality Gate — --fail-on D exits non-zero for CI/CD integration
• Multiple Output Formats — Terminal (rich), HTML (interactive with Chart.js), JSON, Markdown
• Plugin Architecture — Language-agnostic protocol, register new analyzers with one line

Quick Start

pip install dr-huatuo
# or
pipx install dr-huatuo

# Check a Python file
ht check myfile.py

# Check a TypeScript project
ht check frontend/src/ --language typescript

# Check a mixed project (auto-detects Python + TypeScript)
ht check src/ --fail-on D

# Generate interactive HTML report
ht report src/ -f html -o report.html

# Show version and tool status
ht version

Screenshots

Terminal Report (ht report src/)

HTML Report (ht report src/ -f html)

Quality Dimensions

Type safety (mypy errors) is reported as informational — not rated.

CLI Reference

# Quality check (5-dimension profile)
ht check <path>                          # analyze file or directory
ht check src/ --fail-on D               # CI gate: fail on D or F
ht check src/ --fail-on C               # stricter: fail on C, D, or F
ht check src/ --fail-on WARN            # fail on any security warning
ht check src/ --fail-on D --dimension Security  # gate single dimension
ht check src/ -e .venv tests docs       # exclude directories
ht check src/ --language typescript     # filter by language

# Project reports
ht report <path>                         # terminal output (default)
ht report src/ -f html -o report.html   # interactive HTML with Chart.js
ht report src/ -f json -o report.json   # machine-readable JSON
ht report src/ -f markdown -o report.md # markdown for docs

# Info
ht version                               # show version + tool status

Scoring System

Score starts at 100, with deductions per category:

Grades: A (90+) Excellent, B (80+) Good, C (70+) Fair, D (60+) Pass, F (<60) Fail

Tools Orchestrated

Python

Python tools are installed automatically as pip dependencies.

TypeScript

TypeScript tools require Node.js. Install locally: npm install --save-dev eslint typescript typhonjs-escomplex

Roadmap

• Foundation — single-file analyzer, project reporter, tests, CI/CD, PyPI
• Quality Profile & CLI — 5-dimension profile, ht CLI, quality gate, HTML drilldown
• Scoring Consistency — unified scoring formula, tool detection fix
• Analyzer Unification — plugin protocol, PythonAnalyzer, generic field names
• Multi-Language — TypeScript analyzer, mixed-project support
• Research Pipeline — dataset annotation, deduplication, BugsInPy validation

License

MIT