# 1. Clone
git clone https://github.com/FoxPink-dev/odoo-best-practices.git
cd odoo-best-practices

# 2. Run analysis on your Odoo addon (use python3 on Linux, full path on Windows)
python -m analyzer.cli /path/to/your/addon --check

npx @foxpink-dev/odoo-best-practices init /path/to/your/addon

Models: 12
Fields: 142
Violations: 3 violations found
  CRITICAL: 1
  HIGH:     1
  MEDIUM:   1
  LOW:      0

python -m analyzer.cli tests/fixtures/demo_addon --check --format json

name: Odoo Review
on:
  pull_request:
    paths:
      - '**.py'
      - '**/__manifest__.py'
      - '**/*.xml'
      - '**/security/*.csv'

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write
    steps:
      - uses: actions/checkout@v4

      - name: Odoo Static Analysis
        uses: ./.github/actions/odoo-review
        with:
          addon-path: '.'
          fail-on-critical: 'true'
          fail-on-high: 'true'
          baseline: 'true'
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload SARIF to Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: odoo-review-results.sarif
          category: odoo-analyzer
        continue-on-error: true

┌─────────────────────────────────────────────┐
│  ## Odoo Analysis Report                     │
│  | Severity | Count |                       │
│  |----------|-------|                       │
│  | 🔴 CRITICAL | 1 |                        │
│  | 🟠 HIGH     | 1 |                        │
│  | 🟡 MEDIUM   | 1 |                        │
│  | **Total**   | **3** |                    │
│                                              │
│  ### 🔴 CRITICAL (1)                         │
│  - **`models/sale.py:42`** — search() inside │
│    loop                                      │
│    <sub>rule: `search-inside-loop`</sub>     │
└─────────────────────────────────────────────┘

{
  "mcpServers": {
    "odoo-analyzer": {
      "command": "python",
      "args": ["-m", "analyzer.mcp_server", "/path/to/addon"]
    }
  }
}

{
  "mcpServers": {
    "odoo-analyzer": {
      "command": "python",
      "args": ["-m", "analyzer.mcp_server", "/path/to/addon"]
    }
  }
}

{
  "mcpServers": {
    "odoo-analyzer": {
      "command": "python",
      "args": ["-m", "analyzer.mcp_server", "/path/to/addon"]
    }
  }
}

User: "Why does sale.order have no ACL?"
→ Agent calls `search_model("sale.order")` + `models_missing_acl`
→ "Model sale.order is defined at models/sale.py:10 but has no ACL entry in security/ir.model.access.csv"

# Full analysis with markdown report
python -m analyzer.cli path/to/addon

# JSON output for CI pipelines
python -m analyzer.cli path/to/addon --format json

# SARIF for GitHub Code Scanning
python -m analyzer.cli path/to/addon --format sarif -o results.sarif

# Quick check (violations only)
python -m analyzer.cli path/to/addon --check

# Check with baseline suppression (legacy repos)
python -m analyzer.cli path/to/addon --check --baseline

# Generate baseline from existing violations
python -m analyzer.cli path/to/addon --baseline

# Build searchable index for AI tools
python -m analyzer.cli path/to/addon --index -o repo_index

# Rule statistics
python -m analyzer.cli path/to/addon --stats

# Inheritance graph (Mermaid format)
python -m analyzer.cli path/to/addon --graph

python -m analyzer.cli path/to/addon --stats

Repository: my_addon
  Models: 12
  Fields: 142
  Views:  8
  Actions: 5
  ACLs:   10
  Record Rules: 3

Violations by severity:
  CRITICAL:  2
  HIGH:      7
  MEDIUM:    13
  LOW:       21
  ─────────────────
  Total:     43

Top rules violated:
  orm-no-n-plus-1 (CRITICAL)    → 3 violations
  orm-raw-sql (HIGH)            → 2 violations
  security-acl (CRITICAL)       → 2 violations

search-inside-loop
  Severity:   CRITICAL
  Confidence: 98%              ← High accuracy → fix immediately

missing-index
  Severity:   MEDIUM
  Confidence: 60%              ← Possible false positive → review needed

# .github/workflows/odoo-review.yml
- name: Odoo Review
  uses: ./.github/actions/odoo-review
  with:
    fail-on-critical: 'true'

# Step 1: Baseline existing violations
python -m analyzer.cli /path/to/legacy/addon --baseline
# → Creates odoo-baseline.json with 387 accepted violations

# Step 2: Only NEW violations are reported from now on
python -m analyzer.cli /path/to/legacy/addon --check --baseline
# → Only 3 new violations remain

→ "Explain model sale.order"
→ Agent returns: fields, methods, views, inheritance chain, knowledge docs

# Fail build if CRITICAL or HIGH violations exist
- name: Quality Gate
  run: |
    python -m analyzer.cli . --check --format json -o report.json
    python -m ci_tools/check_gate.py report.json

# Generate baseline
python -m analyzer.cli /path/to/addon --baseline

# Check with baseline
python -m analyzer.cli /path/to/addon --check --baseline

{
  "version": 1,
  "addon": "my_addon",
  "timestamp": "2026-06-20T12:00:00Z",
  "total_accepted": 387,
  "accepted": [
    {"rule": "orm-no-n-plus-1", "file": "models/foo.py", "line": 54}
  ]
}

from analyzer import RepositoryStore

store = RepositoryStore("path/to/addon")
store.load()

# Model queries
store.search_model("sale.order")
store.fields_for_model("sale.order")
store.methods_for_model("sale.order")

# Analysis
store.check_code()
store.violations_by_severity("CRITICAL")

# Security audit
store.models_missing_acl()
store.list_acls()

# Graphs
print(store.inheritance_graph_mermaid())

# Summary
print(store.repository_summary())

odoo-best-practices/
├── SKILL.md                       # Entry point — rule index + triggers
├── AGENTS.md                      # Full compiled reference (136 rules)
├── README.md                      # This file
├── rules/                         # 136 rule files (13 categories)
├── bad_patterns/                  # 12 anti-pattern detectors
├── knowledge/                     # 12 core model domain files
├── versions/{14,15,16,17,18,19}/ # Version-specific guides
├── docs/                          # 60 official Odoo docs (14-19)
├── analyzer/                      # Python static analysis engine
│   ├── cli.py                     # CLI: 7 sub-commands
│   ├── checker.py                 # AST rule engine (4 checks)
│   ├── constants.py               # Shared severity constants
│   ├── indexer.py                 # Repository index builder
│   ├── reporter.py                # Markdown/JSON/SARIF report generator
│   ├── baseline.py                # Baseline suppression system
│   ├── sarif.py                   # SARIF v2.1.0 output with fix suggestions
│   ├── store.py                   # RepositoryStore (unified API)
│   ├── mcp_server.py              # MCP protocol server (14 tools)
│   ├── graph.py                   # Inheritance + dependency graphs
│   ├── init_generator.py          # Per-IDE config generator (5 IDEs)
│   └── parsers/
│       ├── common.py              # Shared AST helpers (ast_node_to_value)
│       ├── manifest_parser.py     # AST-safe manifest parsing
│       ├── model_parser.py        # Models, fields, methods, decorators
│       ├── view_parser.py         # Views, actions, menus, templates
│       └── security_parser.py     # ACLs, record rules, groups, categories
├── package.json                   # npm package (scoped @foxpink-dev)
├── bin/                           # npm CLI entry point
├── .npmignore
├── .github/
│   ├── workflows/odoo-review.yml  # PR review CI
│   ├── workflows/publish-npm.yml  # npm publish
│   └── actions/odoo-review/       # Docker action for GitHub CI
│       └── entrypoint.py