🚀 EffortMeter (Johankit)

EffortMeter é uma ferramenta CLI que estima o esforço real de entrega de software (HE — Human Effort) a partir de diffs Git, levando em conta:

• Volume real de mudanças
• Complexidade cognitiva
• Context switching
• Diversidade técnica
• Uso de IA (assistência)
• Configurações customizadas por projeto

Ela gera relatórios locais ou comentários automáticos em Pull Requests no GitHub.

📦 Instalação

Via npm (global)

npm install -g johankit

Ou como dependência de projeto

npm install --save-dev johankit

▶️ Uso Básico

Execute dentro de um repositório Git:

johankit

O comando irá:

1. Detectar automaticamente a branch base (origin/main, main, etc)
2. Calcular o esforço com base no diff
3. Gerar um relatório formatado em Markdown

⚙️ Opções de CLI

johankit [options]

| Opção | Descrição | | -------------- | ------------------------------------------ | | --base <ref> | Define manualmente o commit ou branch base | | --json | Retorna o resultado em JSON (sem template) |

Exemplo:

johankit --base develop --json

🤖 Suporte a Assistência por IA

Você pode informar o nível de assistência de IA criando um arquivo temporário:

// .effort.input.json
{
  "text": "Refatoração com auxílio do Copilot",
  "assistance": 2
}

Após a execução, o arquivo é automaticamente removido.

🧠 Conceito de HE (Human Effort)

O HE não mede linhas de código. Ele estima custo cognitivo + esforço mecânico.

Visão Geral

flowchart TD
    A[Git Diff] --> B[Filtragem de arquivos]
    B --> C[Esforço Mecânico]
    B --> D[Complexidade Cognitiva]
    C --> E[Ajuste por IA]
    D --> E
    E --> F[HE Final]

🧮 Fórmula de Cálculo

1️⃣ Delta Efetivo por Arquivo

Δ = linhas_adicionadas + (linhas_removidas × 0.3)

2️⃣ Massa do Arquivo

massa = ln(1 + Δ) × 2.5

3️⃣ Peso por Tipo de Arquivo

Configurável por glob:

effort:
  weights:
    "**/*.md": 0.4
    "**/*.test.js": 0.7
    "**/*.js": 1.2

massa_final = massa × peso

4️⃣ Esforço Mecânico Total

ME = Σ(massa_final) × coeficiente_base × fator_IA

Padrões:

• coeficiente_base = 0.015

5️⃣ Complexidade Cognitiva

context_switching = log2(arquivos + 1) × 0.5
directory_complexity = log2(diretórios + 1) × 0.8
tech_diversity = log2(extensões + 1) × 0.4

CE = (context_switching + directory_complexity + tech_diversity) × multiplicador_cognitivo

Padrão:

• multiplicador_cognitivo = 0.6

6️⃣ HE Final

HE = ME + CE

🧩 Diagrama Matemático Consolidado

flowchart LR
    A[Δ efetivo] --> B[ln(1+Δ)]
    B --> C[Massa]
    C --> D[Peso por Arquivo]
    D --> E[ME]
    F[Arquivos / Diretórios / Extensões] --> G[CE]
    E --> H[HE]
    G --> H

🗂️ Arquivo de Configuração (johankit.yml)

Opcional, no root do projeto:

ignores:
  - node_modules/**
  - dist/**

effort:
  coeficience: 0.015
  multiply: 0.6

  weights:
    "**/*.md": 0.4
    "**/*.spec.js": 0.7
    "**/*.js": 1.2
    "**/*.yml": 1.4

  assistance:
    - 1.0   # sem IA
    - 0.85  # baixa assistência
    - 0.65  # média
    - 0.45  # alta

🚨 Sinais de Sistema (Signals)

Gerados automaticamente:

| Sinal | Condição | | ------------------------ | -------------- | | Baby Step | ≤ 1 arquivo | | Many Files | > 5 arquivos | | High Context Switching | > 3 diretórios | | High Technical Diversity | > 3 extensões | | Balanced Change | padrão |

🧾 Template de Pull Request

O arquivo templates/pr-template.md é renderizado automaticamente:

sequenceDiagram
    participant Dev
    participant CLI
    participant Git
    participant GitHub

    Dev->>CLI: Executa johankit
    CLI->>Git: diff base...HEAD
    CLI->>CLI: Calcula HE
    CLI->>GitHub: Posta comentário

🔌 Integração com GitHub Actions

Funciona automaticamente quando:

• GITHUB_TOKEN está definido
• O evento é um pull_request

Caso contrário, o relatório é exibido localmente.

📊 Saída JSON (exemplo)

{
  "effort": {
    "raw": "12.40",
    "adjusted": "7.85",
    "savingsPct": "36.7"
  },
  "stats": {
    "files": 6,
    "delta": 420
  }
}

🎯 Objetivo do Projeto

HE não mede produtividade. Mede custo humano.

Ideal para:

• Revisão de PRs
• Métricas de entrega
• Comparação justa entre times
• Análise de impacto real