CodeHealthAnalyzer Documentation

CodeHealthAnalyzer é uma biblioteca Python para análise de saúde de código com foco em três frentes:

violações de tamanho em módulos, classes, funções e templates
CSS e JavaScript inline em templates HTML
erros de linting coletados via Ruff

Principais Funcionalidades

API Python estável com CodeAnalyzer e analyzers especializados
CLI completa com analyze, violations, templates, errors, score, info, dashboard, format e lint
Relatórios em JSON, HTML, Markdown e CSV
Dashboard FastAPI opcional para métricas agregadas
Contrato de relatório tipado e versão centralizada
Configuração por JSON para limites, diretórios e exclusões

Instalação

pip install codehealthanalyzer

Com dashboard:

pip install "codehealthanalyzer[web]"

Uso Rápido

CLI (Interface de Linha de Comando)

# Análise completa do projeto atual
cha analyze .

cha analyze . --format all --output reports
cha violations . --format csv
cha templates . --config cha_config.json
cha errors . --no-json --format markdown
cha dashboard .

API Python

from codehealthanalyzer import CodeAnalyzer

analyzer = CodeAnalyzer(
    ".",
    config={"target_dir": ".", "templates_dir": ["templates"]},
)
report = analyzer.generate_full_report(output_dir="reports")
print(report["summary"]["quality_score"])

Configuração

Exemplo de cha_config.json:

{
  "limits": {
    "python_function": { "yellow": 30, "red": 50 },
    "python_class": { "yellow": 300, "red": 500 },
    "python_module": { "yellow": 500, "red": 1000 },
    "html_template": { "yellow": 150, "red": 200 },
    "test_file": { "yellow": 400, "red": 600 }
  },
  "target_dir": ".",
  "templates_dir": ["templates", "app/templates"],
  "exclude_dirs": ["legacy", "vendor"],
  "ruff_fix": false,
  "no_default_excludes": false
}

Campos suportados:

limits: sobrescreve limites de tamanho
target_dir: diretório analisado pelo Ruff
templates_dir: string ou lista de diretórios de templates
exclude_dirs: string ou lista de diretórios extras a ignorar
ruff_fix: roda ruff check --fix antes da coleta
no_default_excludes: desabilita as exclusões padrão

Detalhamento de relatório no comando analyze:

--detail summary: gera summary_report.json + arquivos por domínio
--detail standard: adiciona analysis_report.json
--detail full: adiciona full_report.json

Contrato de Relatório

O relatório consolidado sempre contém:

{
    "metadata": {...},
    "summary": {...},
    "violations": {...},
    "templates": {...},
    "errors": {...},
    "priorities": [...],
    "quality_score": 0,
}

Os schemas tipados ficam em codehealthanalyzer/schemas.py.

Índice

Conteúdo: