Odoo Doctor 🩺

Unified health scoring for Odoo custom addons.

Combines confidence-aware static analysis with optional external linters (Ruff, Pylint-Odoo) to produce a single 0–100 score per addon — designed for CI pipelines and AI coding agents.

Quick Start

# 1. Chạy ngay (không cần install)
pipx run odoo-doctor scan .

# 2. Install global
pip install odoo-doctor
odoo-doctor scan .

# 3. JSON output cho CI / agents
odoo-doctor scan . --json

# 4. Fail nếu score < 80
odoo-doctor scan . --min-score 80

# 5. Chỉ scan file đã thay đổi (PR review)
odoo-doctor scan . --diff main --json

What it checks

Plus Ruff and Pylint-Odoo findings when those tools are installed.

The full, generated reference (36 rules, with before/after examples) is in docs/rules.md; every finding links to its entry. Disable a rule with odoo-doctor rules disable <rule-name>; write your own with the stable plugin API.

Score explained

Each category score starts at 100 and loses points per high-confidence finding, where each finding deducts tier_impact × category_weight (default weight 1.0; override via [category_weights]). The overall score blends only in-scope categories (those with at least one active rule):

category_score = max(0, 100 − Σ(tier_impact × category_weight))
overall        = 0.4 × min(in_scope_category_scores)
               + 0.6 × avg(in_scope_category_scores)

Tier impacts: P0 = 25, P1 = 10, P2 = 4, P3 = 1.

Each finding deducts points by tier: P0 = −25, P1 = −10, P2 = −4, P3 = −1.
Only high confidence findings count toward the score.

Fix first

Every scan ranks the score-eligible findings of each module by marginal score gain per effort, so you (or an agent) fix the right thing first. The terminal prints the top 5 under Fix first; --json has the top 10 per module as modules.<name>.fix_priorities:

{"rank": 1, "rule": "missing-ondelete", "file_path": "...", "line": 79,
 "impact": 10.0, "effort": 1, "roi": 10.0, "projected_score": 52.1,
 "score_gain": 4.7, "fixable": false}

• effort is a coarse 1-3 estimate per rule (1 mechanical, 2 local code change, 3 restructuring); auto-fixable rules count as 1.
• projected_score is the module score after fixing this finding and every one ranked before it; score_gain is the change this step made. A category that is already at 0 shows +0.0 until enough of its findings are fixed — the weakest category carries the 0.4 × min term, so it is ranked first.

Configuration

odoo-doctor init   # creates odoo-doctor.toml

[odoo-doctor]
odoo_version = "17.0"
addons_paths = ["."]
odoo_source_path = "/path/to/odoo/source"
capabilities = ["enterprise", "owl"]
min_score = 75

[adapters]
ruff = true
pylint_odoo = false

[severity]
"search-in-loop" = "warning"

[ignore]
rules = []
files = ["**/migrations/**"]
modules = []

[category_weights]
Security = 1.5

[surfaces.pr_comment]
min_confidence = "all"
categories = []

[surfaces.ci_failure]
min_confidence = "high"
categories = []

CI Integration

GitHub Actions

The easiest way to integrate Odoo Doctor into GitHub Actions is using our official composite action. See .github/workflows/odoo-doctor.example.yml for a full example.

- name: Odoo Doctor Scan
  uses: minhhq-a1/odoo-doctor@v0.6.0
  with:
    fail-on: warning
    min-score: 75
    diff-base: main
    pr-comment: true
    paths: "."

If you prefer pip install, you can run it directly:

- name: Odoo Doctor (pip)
  run: |
    pip install odoo-doctor
    odoo-doctor scan . --format github --min-score 75 --fail-on error

SARIF & Baseline Mode

For GitHub Code Scanning and IDE integration:

odoo-doctor scan . --format sarif > results.sarif
# Then upload via github/codeql-action/upload-sarif

To capture current debt and block only new findings in CI:

odoo-doctor scan . --write-baseline .odoo-doctor-baseline.json
# Commit the baseline, then in CI:
odoo-doctor scan . --baseline .odoo-doctor-baseline.json --fail-on warning

CI/PR Surfaces

• --format github: Emits GitHub Actions annotations inline.
• --score-delta <base-ref>: Opt-in PR score delta. It does a worktree-isolated second scan and needs git history (fetch-depth: 0 in Actions).
• Sticky PR comment: Posted/updated via gh when --format github runs in a PR with a valid GH_TOKEN. Idempotent via a hidden marker.

CI failure policy

--fail-on <severity> only counts findings admitted by [surfaces.ci_failure], which defaults to P0/P1 at high confidence: style/advisory (P2/P3) and low-confidence findings are reported but never fail a build. Adjust it:

[surfaces.ci_failure]
tiers = ["P0", "P1", "P2"]   # [] = every tier
min_confidence = "high"

Score history & badge

Track the score over time and publish a badge without any server (see docs/score-history.md):

odoo-doctor scan . --history .odoo-doctor/history.jsonl --badge badge.svg
odoo-doctor history show .odoo-doctor/history.jsonl --max-drop 3   # exit 2 on regression
odoo-doctor history import history.jsonl old-report.json           # pre-0.4.0 reports

pre-commit

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: odoo-doctor
        name: Odoo Doctor
        language: system
        entry: odoo-doctor scan --diff HEAD --fail-on error
        pass_filenames: false
        types: [python]

Agent Usage

Odoo Doctor is designed for AI coding agents. Install the SKILL.md files:

odoo-doctor install   # installs to .odoo-doctor/skills/

Then in your agent workflow:

# After editing Odoo code
odoo-doctor scan . --diff main --json

# Fix P0/P1 findings with confidence: "high"
# Re-scan to verify fixes
odoo-doctor scan . --diff main --json

Use odoo-doctor rules explain <rule-name> to understand any finding (description, why, fix, examples and a docs link).

Generating stubs for your Odoo version

Bundled stubs cover 17.0, 18.0, 19.0 (core models only).
For full accuracy, generate from source or a live instance:

# From Odoo source checkout
python -m odoo_doctor.graph.stubs.build_stubs source \
  --odoo-path /path/to/odoo \
  --version 17.0

# From a live Odoo instance (no source needed)
python -m odoo_doctor.graph.stubs.build_stubs rpc \
  --rpc-url http://localhost:8069 \
  --rpc-db mydb \
  --rpc-password admin \
  --version 17.0

The generated JSON is written to src/odoo_doctor/graph/stubs/data/<version>.json
(or --output <path> for a custom location).

Inline suppression

x = self.env.cr.execute(f"SELECT ...")  # odoo-doctor: disable=raw-sql-string-interpolation

<record id="my_record" model="ir.ui.view">  <!-- odoo-doctor: disable=duplicate-xml-id -->

Exit codes

odoo-doctor history show --max-drop N also exits 2 when the score regressed.

Development

git clone https://github.com/minhhq-a1/odoo-doctor
cd odoo-doctor
pip install -e ".[dev]"
pytest                    # 492 test cases
pytest --cov=odoo_doctor  # with coverage