feat(doctor): hawkapi doctor — one-shot health check CLI with 18 rules across 5 categories

Adds `hawkapi doctor app:app` subcommand that lints a live HawkAPI
instance against 18 rules spanning security (DOC010-014), observability
(DOC020-023), performance (DOC030-033), correctness (DOC040-042), and
deps (DOC050-051). Outputs human-readable or JSON reports; exits 0/1/2.

Author: Berik Ashimov

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- `hawkapi doctor <APP_SPEC>` — one-shot health-check CLI that lints a running HawkAPI app against 18 rules across 5 categories (security, observability, performance, correctness, deps). Human and JSON output, `--severity` filter, `--fix` scaffold, exit codes 0/1/2. Target v0.1.4.
+
 ## [0.1.3] - 2026-04-19
 
 ### Added

README.md

@@ -1004,6 +1004,11 @@ hawkapi migrate path/to/fastapi_project
 hawkapi migrate path/to/fastapi_project --dry-run       # preview diffs only
 hawkapi migrate path/to/fastapi_project --convert-models # also rewrite Pydantic BaseModel → msgspec.Struct
 hawkapi migrate path/to/fastapi_project --output ./migrated  # write to separate directory
+
+# Health-check a running app (18 rules across 5 categories)
+hawkapi doctor app:app
+hawkapi doctor app:app --format=json
+hawkapi doctor app:app --severity=warn   # only warnings and errors
 ```
 
 `hawkapi init` creates `.env` and `.env.example` files with commented-out HawkAPI configuration templates. Existing files are skipped.
@@ -1012,6 +1017,8 @@ hawkapi migrate path/to/fastapi_project --output ./migrated  # write to separate
 
 `hawkapi migrate` uses AST rewriting (libcst) to replace FastAPI imports, decorators, and patterns with their HawkAPI equivalents. See [docs/guide/migration-from-fastapi.md](docs/guide/migration-from-fastapi.md).
 
+`hawkapi doctor` lints a live app for security misconfigurations, missing observability middleware, performance anti-patterns, and outdated dependencies. Exits 0 (clean), 1 (warnings), or 2 (errors). See [docs/guide/doctor.md](docs/guide/doctor.md).
+
 ---
 
 ## Configuration

docs/guide/doctor.md

@@ -0,0 +1,132 @@
+# Doctor
+
+`hawkapi doctor` is a one-shot health-check CLI that lints a running HawkAPI application for common misconfigurations across security, observability, performance, correctness, and dependency hygiene.
+
+## Usage
+
+```bash
+hawkapi doctor <APP_SPEC> [--format={human,json}] [--severity={info,warn,error}] [--fix]
+```
+
+| Argument | Default | Description |
+|---|---|---|
+| `APP_SPEC` | required | `module:attr` reference, e.g. `main:app` |
+| `--format` | `human` | Output format: `human` (coloured TTY) or `json` |
+| `--severity` | `info` | Minimum severity to report: `info`, `warn`, or `error` |
+| `--fix` | off | Apply safe auto-fixes (v1: prints a notice; no fixes implemented yet) |
+
+**Exit codes:**
+
+| Code | Meaning |
+|---|---|
+| `0` | No findings at or above the chosen severity |
+| `1` | At least one warning |
+| `2` | At least one error |
+
+### Example
+
+```bash
+$ hawkapi doctor main:app
+hawkapi doctor — main:app
+
+✗  DOC010  DOC010
+   CORSMiddleware allows all origins ('*'). This exposes all endpoints to any origin.
+   Fix: Whitelist specific origins in CORSMiddleware(allow_origins=[...]).
+   https://hawkapi.ashimov.com/doctor/DOC010
+
+⚠  DOC011  DOC011
+   State-changing routes (POST/PUT/PATCH/DELETE) exist but CSRFMiddleware is not installed.
+   Fix: Add app.add_middleware(CSRFMiddleware, secret=...) to protect browser-facing endpoints.
+   https://hawkapi.ashimov.com/doctor/DOC011
+
+Summary: 1 errors, 1 warnings, 0 info · exit 2
+```
+
+### JSON output
+
+```bash
+hawkapi doctor main:app --format=json
+```
+
+```json
+{
+  "app": "main:app",
+  "summary": {"errors": 1, "warnings": 1, "info": 0, "total": 2},
+  "findings": [
+    {
+      "rule_id": "DOC010",
+      "severity": "error",
+      "message": "CORSMiddleware allows all origins ('*').",
+      "fix": "Whitelist specific origins in CORSMiddleware(allow_origins=[...]).",
+      "location": null,
+      "docs_url": "https://hawkapi.ashimov.com/doctor/DOC010"
+    }
+  ]
+}
+```
+
+## Rule reference
+
+### Security
+
+| ID | Severity | Title | Fix |
+|---|---|---|---|
+| `DOC010` | error | CORS allows `*` in production | Whitelist specific origins in `CORSMiddleware(allow_origins=[...])` |
+| `DOC011` | warn | CSRFMiddleware not installed but state-changing routes exist | Add `CSRFMiddleware` |
+| `DOC012` | warn | TrustedProxyMiddleware missing behind a known proxy | Add `TrustedProxyMiddleware` |
+| `DOC013` | error | Hardcoded placeholder secrets on `app.state` | Load secrets from env vars or a secrets manager |
+| `DOC014` | info/warn | HTTPSRedirectMiddleware absent | Add `HTTPSRedirectMiddleware` (warn if `ENV=production`) |
+
+### Observability
+
+| ID | Severity | Title | Fix |
+|---|---|---|---|
+| `DOC020` | warn | No request-ID / observability middleware | Add `RequestIDMiddleware` or `StructuredLoggingMiddleware` |
+| `DOC021` | info | No `/metrics` endpoint (prometheus_client installed) | Add `PrometheusMiddleware` |
+| `DOC022` | info | opentelemetry installed but no OTel wiring | Install hawkapi-otel and register the plugin |
+| `DOC023` | info | sentry_sdk installed but no Sentry wiring | Install hawkapi-sentry and register the plugin |
+
+### Performance
+
+| ID | Severity | Title | Fix |
+|---|---|---|---|
+| `DOC030` | info/error | `debug=True` in production | Set `debug=False` (error if `ENV=production`) |
+| `DOC031` | warn | GZipMiddleware absent and routes return large payloads | Add `GZipMiddleware(minimum_size=1000)` |
+| `DOC032` | warn | Handler returns bare `dict`/`list` without `response_model` | Add a msgspec.Struct return annotation |
+| `DOC033` | info | Heavy I/O routes without a bulkhead | Wrap with `@bulkhead(...)` |
+
+### Correctness
+
+| ID | Severity | Title | Fix |
+|---|---|---|---|
+| `DOC040` | info | Route handler missing return annotation | Add a return type annotation |
+| `DOC041` | info | Route without docstring or `summary=` | Add a docstring or `summary=` parameter |
+| `DOC042` | warn | Suspicious middleware order: CORS after auth | Add `CORSMiddleware` before authentication middleware |
+
+### Dependencies
+
+| ID | Severity | Title | Fix |
+|---|---|---|---|
+| `DOC050` | info | HawkAPI version older than latest on PyPI | `pip install --upgrade hawkapi` |
+| `DOC051` | warn | msgspec < 0.19 | `pip install --upgrade 'msgspec>=0.19'` |
+
+## `--fix` mode
+
+`--fix` is reserved for safe, deterministic auto-fixes. In v1, no rules implement `auto_fix`, so the flag prints a notice and exits normally. Future rules may opt in on a case-by-case basis.
+
+## CI integration
+
+Add a step to your GitHub Actions workflow to gate deployments on doctor output:
+
+```yaml
+- name: hawkapi doctor
+  run: |
+    uv run hawkapi doctor main:app --severity=warn --format=json
+```
+
+This step exits non-zero if any warning or error is found, blocking the workflow. Use `--severity=error` to only gate on errors:
+
+```yaml
+- name: hawkapi doctor (errors only)
+  run: uv run hawkapi doctor main:app --severity=error
+```

mkdocs.yml

@@ -57,6 +57,7 @@ nav:
       - Bulkhead: guide/bulkhead.md
       - Free-threaded Python (PEP 703): guide/free-threaded.md
       - Migration from FastAPI: guide/migration-from-fastapi.md
+      - Doctor: guide/doctor.md
   - API Reference: api/index.md
 
 markdown_extensions:

src/hawkapi/cli.py

@@ -149,6 +149,34 @@ def main(argv: list[str] | None = None) -> None:
     _source.add_argument("--spec", help="path to openapi.json")
     p_gen.add_argument("--out", required=True, help="output directory")
 
+    # `hawkapi doctor` subcommand
+    doctor_parser = subparsers.add_parser(
+        "doctor",
+        help="Run health checks on a HawkAPI application",
+    )
+    doctor_parser.add_argument(
+        "app",
+        help="Application to check (module:attribute format, e.g. main:app)",
+    )
+    doctor_parser.add_argument(
+        "--format",
+        dest="output_format",
+        choices=["human", "json"],
+        default="human",
+        help="Output format (default: human)",
+    )
+    doctor_parser.add_argument(
+        "--severity",
+        choices=["info", "warn", "error"],
+        default="info",
+        help="Minimum severity to report (default: info)",
+    )
+    doctor_parser.add_argument(
+        "--fix",
+        action="store_true",
+        help="Apply safe auto-fixes where available (v1: none implemented)",
+    )
+
     # `hawkapi migrate` subcommand
     migrate_parser = subparsers.add_parser(
         "migrate",
@@ -192,12 +220,39 @@ def main(argv: list[str] | None = None) -> None:
         _run_new(args)
     elif args.command == "init":
         _run_init(args)
+    elif args.command == "doctor":
+        sys.exit(_run_doctor(args))
     elif args.command == "migrate":
         _run_migrate(args)
     elif args.command == "gen-client":
         _run_gen_client(args)
 
 
+def _run_doctor(args: argparse.Namespace) -> int:
+    """Run health checks on the given application and return an exit code."""
+    from hawkapi.doctor._formatter import exit_code, format_human, format_json
+    from hawkapi.doctor._runner import load_app, run
+    from hawkapi.doctor._types import Severity
+
+    module_path, attr_name = _parse_ref(args.app)
+    app = load_app(module_path, attr_name)
+
+    _SEV_MAP = {"info": Severity.INFO, "warn": Severity.WARN, "error": Severity.ERROR}
+    min_sev = _SEV_MAP[args.severity]
+
+    if args.fix:
+        print("--fix: no auto-fixable findings in v1.")
+
+    findings = run(app, min_severity=min_sev)
+
+    if args.output_format == "json":
+        print(format_json(findings, args.app))
+    else:
+        print(format_human(findings, args.app))
+
+    return exit_code(findings)
+
+
 def _run_dev(args: argparse.Namespace) -> None:
     """Run the development server using uvicorn."""
     try:

src/hawkapi/doctor/__init__.py

@@ -0,0 +1,20 @@
+"""hawkapi doctor — one-shot health-check CLI for HawkAPI applications."""
+
+from __future__ import annotations
+
+from hawkapi.doctor._formatter import exit_code, format_human, format_json
+from hawkapi.doctor._runner import load_app, run
+from hawkapi.doctor._types import Finding, Rule, Severity
+from hawkapi.doctor.rules import ALL_RULES
+
+__all__ = [
+    "ALL_RULES",
+    "Finding",
+    "Rule",
+    "Severity",
+    "exit_code",
+    "format_human",
+    "format_json",
+    "load_app",
+    "run",
+]

src/hawkapi/doctor/_formatter.py

@@ -0,0 +1,118 @@
+"""Human-readable and JSON output formatters for doctor findings."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from hawkapi.doctor._types import Finding, Severity
+
+# ANSI colour codes — only applied when stdout is a TTY.
+_RED = "\033[31m"
+_YELLOW = "\033[33m"
+_CYAN = "\033[36m"
+_RESET = "\033[0m"
+
+_EMOJI = {
+    Severity.ERROR: "✗",
+    Severity.WARN: "⚠",
+    Severity.INFO: "ℹ",
+}
+
+
+def _colour(text: str, code: str) -> str:
+    if sys.stdout.isatty():
+        return f"{code}{text}{_RESET}"
+    return text
+
+
+def _severity_colour(sev: Severity) -> str:
+    if sev == Severity.ERROR:
+        return _RED
+    if sev == Severity.WARN:
+        return _YELLOW
+    return _CYAN
+
+
+def exit_code(findings: list[Finding]) -> int:
+    """Return the appropriate exit code for the given findings list."""
+    if any(f.severity == Severity.ERROR for f in findings):
+        return 2
+    if any(f.severity == Severity.WARN for f in findings):
+        return 1
+    return 0
+
+
+def format_human(findings: list[Finding], app_spec: str) -> str:
+    """Render findings as a human-readable report grouped by severity."""
+    lines: list[str] = []
+    lines.append(f"hawkapi doctor — {app_spec}")
+    lines.append("")
+
+    if not findings:
+        lines.append("No findings. All checks passed.")
+        lines.append("")
+        lines.append("Summary: 0 errors, 0 warnings, 0 info · exit 0")
+        return "\n".join(lines)
+
+    ordered = sorted(findings, key=lambda f: -f.severity)
+
+    for finding in ordered:
+        emoji = _EMOJI[finding.severity]
+        col = _severity_colour(finding.severity)
+        loc = finding.location or finding.rule_id
+        header = _colour(f"{emoji}  {finding.rule_id}  {loc}", col)
+        lines.append(header)
+        lines.append(f"   {finding.message}")
+        if finding.fix:
+            lines.append(f"   Fix: {finding.fix}")
+        if finding.docs_url:
+            lines.append(f"   {finding.docs_url}")
+        lines.append("")
+
+    errors = sum(1 for f in findings if f.severity == Severity.ERROR)
+    warnings = sum(1 for f in findings if f.severity == Severity.WARN)
+    info = sum(1 for f in findings if f.severity == Severity.INFO)
+    code = exit_code(findings)
+    lines.append(
+        f"Summary: {errors} error{'s' if errors != 1 else ''}, "
+        f"{warnings} warning{'s' if warnings != 1 else ''}, "
+        f"{info} info · exit {code}"
+    )
+    return "\n".join(lines)
+
+
+def format_json(findings: list[Finding], app_spec: str) -> str:
+    """Render findings as a stable JSON document."""
+    errors = sum(1 for f in findings if f.severity == Severity.ERROR)
+    warnings = sum(1 for f in findings if f.severity == Severity.WARN)
+    info = sum(1 for f in findings if f.severity == Severity.INFO)
+
+    _SEV_STR: dict[Severity, str] = {
+        Severity.ERROR: "error",
+        Severity.WARN: "warning",
+        Severity.INFO: "info",
+    }
+
+    payload: dict[str, Any] = {
+        "app": app_spec,
+        "summary": {
+            "errors": errors,
+            "warnings": warnings,
+            "info": info,
+            "total": len(findings),
+        },
+        "findings": [
+            {
+                "rule_id": f.rule_id,
+                "severity": _SEV_STR[f.severity],
+                "message": f.message,
+                "fix": f.fix,
+                "location": f.location,
+                "docs_url": f.docs_url,
+            }
+            for f in findings
+        ],
+    }
+    return json.dumps(payload, indent=2)