@followthecode/cli/README.md

CLI tool for Git repository analysis and data collection

# FTC CLI - Ferramenta de Análise de Repositórios Git

Ferramenta de linha de comando (CLI) para análise de repositórios Git, desenvolvida seguindo a arquitetura Vertical Slice do projeto FTC.

## Funcionalidades

- ✅ Total de commits no repositório
- ✅ Lista de autores e quantidade de commits por autor
- ✅ Número total de arquivos alterados
- ✅ Lista dos arquivos alterados com quantidade de alterações (adições/remoções)
- ✅ Relatório resumido com datas dos primeiros e últimos commits
- ✅ **Suporte a repositórios remotos** (clona automaticamente)
- ✅ Filtros por data (--startDate e --endDate)
- ✅ Exportação em JSON (--json)
- ✅ **Exportação em CSV detalhado** (--csv) com informações por commit
- ✅ **Tratamento robusto de erros** com mensagens claras
- ✅ **Testes automatizados** para validação de funcionalidades
- ✅ **Suporte a Docker** para execução em containers
- ✅ **Uso como ferramenta global (dotnet tool)**

## Simulando/Executando localmente via Docker CLI

Você pode rodar o FTC CLI via Docker em ambiente local, sem scripts auxiliares, seguindo estes passos:

### 1. Build da imagem Docker localmente

No diretório do projeto (onde está o Dockerfile):

```sh
docker build -t ftc:latest .
```

### 2. Executar a CLI com repositório local

Supondo que você tenha um repositório local em uma pasta chamada `meu-repo` no seu diretório atual:

#### Linux/macOS
```sh
docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --json
```

#### Windows (cmd/powershell)
```bat
docker run --rm -v "%cd%:/repo" ftc:latest collect code "/repo/meu-repo" --json
```

- O volume `-v "$PWD:/repo"` (ou `%cd%:/repo` no Windows) faz com que a pasta atual do host seja montada como `/repo` dentro do container.
- O parâmetro `collect code "/repo/meu-repo"` aponta para o caminho do repositório dentro do container.

### 3. Executar a CLI com repositório remoto

Você não precisa mapear volumes para repositórios remotos:

```sh
docker run --rm ftc:latest collect code "https://github.com/exemplo/repositorio.git" --json
```

### 4. Exemplo com filtros de data

```sh
docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --startDate 2024-01-01 --endDate 2024-12-31 --json
```

### 5. Ver ajuda da CLI

```sh
docker run --rm ftc:latest --help
```

> **Resumo:**
> - Sempre use `-v "$PWD:/repo"` (Linux/macOS) ou `-v "%cd%:/repo"` (Windows) para acessar repositórios locais.
> - O caminho passado para `collect code` deve ser o caminho dentro do container, por exemplo, `"/repo/meu-repo"`.
> - Para repositórios remotos, basta passar a URL.

## Uso moderno via Docker CLI

Execute diretamente, sem scripts auxiliares:

### Linux/macOS
```sh
docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --json
```

### Windows (cmd/powershell)
```bat
docker run --rm -v "%cd%:/repo" ftc:latest collect code "/repo/meu-repo" --json
```

### Repositório remoto
```sh
docker run --rm ftc:latest collect code "https://github.com/exemplo/repositorio.git" --json
```

### Com filtros de data
```sh
docker run --rm -v "$PWD:/repo" ftc:latest collect code "/repo/meu-repo" --startDate 2024-01-01 --endDate 2024-12-31 --json
```

> **Dica:**
> - O volume `-v "$PWD:/repo"` (ou `%cd%:/repo` no Windows) permite que o container acesse seu repositório local.

## ⚠️ Problemas de Instalação

Se você encontrar problemas durante a instalação do CLI, como:

- Avisos sobre `node-domexception` deprecado
- Erros de permissão EPERM no Windows
- Problemas de limpeza de cache

Consulte a seção de troubleshooting abaixo.

### Solução Rápida para Windows

Execute o script de correção como Administrador:

```powershell
# Abrir PowerShell como Administrador
.\scripts\fix-permissions.ps1

# Ou com limpeza forçada
.\scripts\fix-permissions.ps1 -Force
```

## 🧪 Testando a Instalação

Antes de publicar uma nova versão, é importante testar a instalação em diferentes ambientes.

### Testes Automatizados

#### Windows
```powershell
# Teste básico
npm run test-installation

# Teste com limpeza prévia
npm run test-installation:clean

# Teste com output detalhado
npm run test-installation:verbose
```

#### Linux/macOS
```bash
# Teste básico
npm run test-installation:linux

# Teste com limpeza prévia
npm run test-installation:linux:clean
```

### Testes Manuais

```bash
# Criar repositório de teste
mkdir test-repo && cd test-repo
git init && echo "# Test" > README.md
git add . && git commit -m "Initial"
cd ..

# Testar funcionalidades
bin/ftc collect code ./test-repo --json
bin/ftc collect code https://github.com/exemplo/repositorio.git --json
```

Para mais detalhes, consulte a seção de testes abaixo.
> - O comando `collect code "/repo/meu-repo"` deve apontar para o caminho dentro do container.

## Uso como ferramenta global (dotnet tool)

Após instalar:

```sh
dotnet tool install --global --add-source ./bin/Release ftc.cli
```

Execute de qualquer lugar:

```sh
ftc collect code "./caminho/para/meu-repo" --json
```

Exemplo com repositório remoto e filtros:

```sh
ftc collect code "https://github.com/exemplo/repositorio.git" --startDate 2024-01-01 --endDate 2024-12-31 --json
```

Para ajuda:

```sh
ftc --help
```

## Uso

### Execução Local

#### Análise de repositório local
```bash
dotnet run -- collect code /caminho/para/repositorio
```

#### Análise de repositório remoto
```bash
dotnet run -- collect code https://github.com/exemplo/repositorio.git
```

#### Com filtros de data
```bash
dotnet run -- collect code /caminho/para/repositorio --startDate 2024-01-01 --endDate 2024-12-31
```

#### Exportação em JSON
```bash
dotnet run -- collect code /caminho/para/repositorio --json
```

#### Exportação em CSV detalhado
```bash
dotnet run -- collect code /caminho/para/repositorio --csv
```

#### Exportação para S3
```bash
dotnet run -- collect code /caminho/para/repositorio --csv --export s3
```

### Execução com Docker

#### Construir e executar
```bash
# Linux/macOS
./scripts/docker-run.sh collect code /caminho/para/repositorio

# Windows
scripts\docker-run.bat collect code C:\caminho\para\repositorio
```

#### Análise de repositório remoto
```bash
# Linux/macOS
./scripts/docker-run.sh collect code https://github.com/exemplo/repositorio.git

# Windows
scripts\docker-run.bat collect code https://github.com/exemplo/repositorio.git
```

#### Com filtros e JSON
```bash
# Linux/macOS
./scripts/docker-run.sh code /caminho/para/repositorio --startDate 2024-01-01 --json

# Windows
scripts\docker-run.bat code C:\caminho\para\repositorio --startDate 2024-01-01 --json
```

#### Opções do Docker Runner
```bash
# Mostrar ajuda
./scripts/docker-run.sh --help

# Reconstruir imagem
./scripts/docker-run.sh --build collect code /caminho/para/repositorio

# Limpar containers
./scripts/docker-run.sh --clean
```

#### Execução direta com Docker
```bash
# Construir imagem
docker-compose build

# Executar CLI
docker-compose run --rm ftc collect code /caminho/para/repositorio

# Executar com volumes mapeados
docker run --rm -v $(pwd)/repos:/repos:ro ftc:latest collect code /repos/meu-projeto
```

## Opções

- `collect`: Comando para coleta de dados
- `code`: Caminho local ou URL do repositório Git (obrigatório)
- `--startDate`: Data inicial no formato yyyy-MM-dd (opcional)
- `--endDate`: Data final no formato yyyy-MM-dd (opcional)
- `--json`: Exportar resultado em formato JSON (opcional)
- `--csv`: Exportar resultado em formato CSV detalhado (opcional)
- `--export`: Destino de exportação: local:/caminho/arquivo.json ou s3 (opcional)

## Repositórios Suportados

### Locais
- Caminhos absolutos: `C:\caminho\para\repositorio`
- Caminhos relativos: `./repositorio`, `../repositorio`

### Remotos
- HTTPS: `https://github.com/exemplo/repositorio.git`
- HTTP: `http://github.com/exemplo/repositorio.git`
- SSH: `git@github.com/exemplo/repositorio.git`
- Git: `git://github.com/exemplo/repositorio.git`

## Exemplo de Saída

### Formato padrão
```
Analisando repositório: https://github.com/exemplo/repositorio.git
Tipo: Remoto
Clonando repositório: https://github.com/exemplo/repositorio.git
Pasta temporária: /tmp/ftc-cli-12345678-1234-1234-1234-123456789abc
Repositório clonado com sucesso.

📊 Total de commits: 150

👥 Autores:
  • Desenvolvedor A <dev.a@exemplo.com>: 45 commits
  • Desenvolvedor B <dev.b@exemplo.com>: 38 commits
  • Desenvolvedor C <dev.c@exemplo.com>: 27 commits

📁 Total de arquivos alterados: 89
📄 Arquivos alterados:
  • src/Program.cs: +120 -45
  • src/Models.cs: +89 -12
  • README.md: +15 -3
  ... e mais 86 arquivos

📅 Primeiro commit: 2024-01-15 10:30:00
📅 Último commit: 2024-12-20 16:45:30
```

### Formato JSON
```json
{
  "totalCommits": 150,
  "authors": [
    {
      "name": "Desenvolvedor A",
      "email": "dev.a@exemplo.com",
      "commits": 45
    }
  ],
  "totalFilesChanged": 89,
  "files": [
    {
      "filePath": "src/Program.cs",
      "additions": 120,
      "deletions": 45
    }
  ],
  "firstCommitDate": "2024-01-15T10:30:00+00:00",
  "lastCommitDate": "2024-12-20T16:45:30+00:00"
}
```

### Formato CSV
```csv
nomeRepositorio;idRepositorio;dataCommit;idCommit;nomeAutor;emailAutor;nomeArquivo;caminhoArquivo;linhasAdicionadas;linhasRemovidas
meu-repo;abc123;2024-01-15 10:30:00;def456;Desenvolvedor A;dev.a@exemplo.com;Program.cs;src/Program.cs;120;45
meu-repo;abc123;2024-01-15 10:30:00;def456;Desenvolvedor A;dev.a@exemplo.com;Models.cs;src/Models.cs;89;12
meu-repo;abc123;2024-01-16 14:20:00;ghi789;Desenvolvedor B;dev.b@exemplo.com;README.md;README.md;15;3
```

O formato CSV inclui:
- **nomeRepositorio**: Nome do repositório
- **idRepositorio**: ID do repositório (SHA do HEAD)
- **dataCommit**: Data e hora do commit
- **idCommit**: SHA do commit
- **nomeAutor**: Nome do autor do commit
- **emailAutor**: Email do autor do commit
- **nomeArquivo**: Nome do arquivo alterado
- **caminhoArquivo**: Caminho completo do arquivo
- **linhasAdicionadas**: Número de linhas adicionadas
- **linhasRemovidas**: Número de linhas removidas

## Tratamento de Erros

A CLI fornece mensagens de erro claras e específicas:

- **Repositório não encontrado**: Verifica se o caminho existe
- **Repositório Git inválido**: Valida se é um repositório Git válido
- **Sem commits**: Verifica se há commits para análise
- **Período sem commits**: Avisa quando não há commits no período especificado
- **Datas inválidas**: Valida formato e ordem das datas
- **Erro de clonagem**: Trata falhas na clonagem de repositórios remotos

## Arquitetura

O projeto segue a arquitetura Vertical Slice do FTC, organizando funcionalidades em slices independentes com suas próprias responsabilidades.

## Docker

### Estrutura Docker
```
Dockerfile                    # Multi-stage build otimizado
.dockerignore                 # Exclusões para build
docker-compose.yml            # Configuração do container
```

### Características da Imagem
- **Multi-stage build**: Otimiza tamanho da imagem
- **Runtime .NET 8**: Imagem base leve
- **Git instalado**: Suporte a repositórios remotos
- **Volumes mapeados**: Acesso a repositórios locais
- **Timezone configurado**: UTC

### Volumes Docker
- `./repos:/repos:ro`: Mapeia repositórios locais (somente leitura)
- `./temp:/tmp`: Pasta temporária para persistência

## Testes

O projeto inclui testes automatizados para validação de funcionalidades:

```bash
# Executar todos os testes
dotnet test

# Executar testes específicos
dotnet test --filter "RepositoryTests"
```

### Cobertura de Testes
- ✅ Detecção de repositórios remotos vs locais
- ✅ Validação de URLs HTTPS, HTTP, SSH, Git
- ✅ Validação de caminhos locais e relativos

## Desenvolvimento

### Compilar
```bash
dotnet build
```

### Executar Localmente
```bash
dotnet run -- [argumentos]
```

### Executar com Docker
```bash
# Linux/macOS
./scripts/docker-run.sh [argumentos]

# Windows
scripts\docker-run.bat [argumentos]
```

### Testar
```bash
# Testar com um repositório local
dotnet run -- collect code C:\caminho\para\repositorio

# Testar com repositório remoto
dotnet run -- collect code https://github.com/exemplo/repositorio.git

# Testar com filtros
dotnet run -- collect code C:\caminho\para\repositorio --startDate 2024-01-01 --endDate 2024-12-31 --json

# Executar testes
dotnet test

# Testar com Docker
./scripts/docker-run.sh collect code C:\caminho\para\repositorio
```

## Melhorias Implementadas

### ✅ Suporte a Repositórios Remotos
- Detecção automática de URLs vs caminhos locais
- Clonagem automática para pasta temporária
- Limpeza automática após análise
- Suporte a múltiplos protocolos (HTTPS, HTTP, SSH, Git)

### ✅ Testes Automatizados
- Testes unitários para detecção de repositórios
- Cobertura de diferentes tipos de URLs
- Validação de caminhos locais e relativos
- Integração com xUnit

### ✅ Tratamento Robusto de Erros
- Mensagens de erro específicas e úteis
- Validação de argumentos de entrada
- Verificação de repositórios válidos
- Tratamento de exceções com contexto
- Interface melhorada com emojis e formatação

### ✅ Suporte a Docker
- Multi-stage build otimizado
- Scripts para Linux/macOS e Windows
- Volumes mapeados para repositórios locais
- Configuração de timezone
- Docker Compose para facilitar uso 

## Exportação de resultados (local e S3)

A CLI permite exportar o resultado da análise para um arquivo local ou diretamente para um bucket S3.

### Exportar JSON localmente
```sh
ftc collect code "./meu-repo" --json --export local:./resultado.json
```

### Exportar CSV localmente
```sh
ftc collect code "./meu-repo" --csv --export local:./resultado.csv
```

### Exportar para S3 (JSON)
```sh
ftc collect code "./meu-repo" --json --export s3
```

### Exportar para S3 (CSV)
```sh
ftc collect code "./meu-repo" --csv --export s3
```

### Exportar para S3 (bucket e key customizados)
```sh
ftc collect code "./meu-repo" --csv --export s3: --s3-bucket "meu-bucket"
```

### Exportar para S3 (bucket/key no próprio parâmetro)
```sh
ftc collect code "./meu-repo" --csv --export s3://meu-bucket/analises/resultado.csv
```

- Se `--s3-bucket` não for informado, será usado o bucket padrão configurado.
- Para JSON: Se `--s3-key` não for informado, será usado o padrão `analises/<nome_repositorio>-ano-mes-dia.json`.
- Para CSV: Se `--s3-key` não for informado, será usado o padrão `analises/<nome_repositorio>-ano-mes-dia.csv`.
- O parâmetro `--s3-region` pode ser usado para especificar a região AWS.