@justmpm/ai-tool 0.7.10 → 0.8.0

package/README.md

@@ -1,10 +1,10 @@
 # ai-tool
 
-Ferramenta de analise de dependencias e impacto para projetos TypeScript/JavaScript.
+Ferramenta de análise de dependências e impacto para projetos TypeScript/JavaScript.
 
 Usa [Skott](https://github.com/antoine-coulon/skott) + [Knip](https://knip.dev) + [ts-morph](https://ts-morph.com) internamente.
 
-## Instalacao
+## Instalação
 
 ```bash
 # Via npx (sem instalar)
@@ -21,7 +21,7 @@ npm install -D @justmpm/ai-tool
 
 ### `map` - Mapa do Projeto
 
-Gera um resumo compacto do projeto com contagens, areas e alertas.
+Gera um resumo compacto do projeto com contagens, áreas e alertas.
 
 ```bash
 ai-tool map           # Resumo compacto (otimizado para tokens)
@@ -48,11 +48,11 @@ ai-tool map --format=json
 **Output (--full):**
 - Lista completa de arquivos por pasta
 - Estrutura detalhada de pastas
-- Dependencias circulares listadas
+- Dependências circulares listadas
 
-### `dead` - Codigo Morto
+### `dead` - Código Morto
 
-Detecta arquivos, exports e dependencias nao utilizados.
+Detecta arquivos, exports e dependências não utilizados.
 
 ```bash
 ai-tool dead
@@ -61,13 +61,13 @@ ai-tool dead --fix  # Remove automaticamente
 ```
 
 **Detecta:**
-- Arquivos orfaos (ninguem importa)
-- Exports nao utilizados
-- Dependencias npm nao usadas
+- Arquivos órfãos (ninguém importa)
+- Exports não utilizados
+- Dependências npm não usadas
 
-### `impact` - Analise de Impacto
+### `impact` - Análise de Impacto
 
-Analisa o impacto de modificar um arquivo especifico.
+Analisa o impacto de modificar um arquivo específico.
 
 ```bash
 ai-tool impact Button
@@ -76,12 +76,12 @@ ai-tool impact useAuth --format=json
 ```
 
 **Output:**
-- **Upstream**: Quem importa este arquivo (afetados por mudancas)
-- **Downstream**: O que este arquivo importa (dependencias)
-- **Riscos**: Arquivo critico, dependencias circulares, etc.
-- **Sugestoes**: Recomendacoes para modificacao segura
+- **Upstream**: Quem importa este arquivo (afetados por mudanças)
+- **Downstream**: O que este arquivo importa (dependências)
+- **Riscos**: Arquivo crítico, dependências circulares, etc.
+- **Sugestões**: Recomendações para modificação segura
 
-### `suggest` - Sugestao de Leitura
+### `suggest` - Sugestão de Leitura
 
 Sugere arquivos para ler ANTES de modificar um arquivo.
 
@@ -92,59 +92,59 @@ ai-tool suggest src/hooks/useAuth.ts --limit=5
 
 **Prioridades:**
 - **Critical**: Tipos/interfaces usados pelo arquivo
-- **High**: Dependencias diretas (imports)
+- **High**: Dependências diretas (imports)
 - **Medium**: Upstream (quem usa o arquivo)
 - **Low**: Testes relacionados
 
 ### `context` - Contexto do Arquivo
 
-Extrai assinaturas de funcoes e tipos SEM a implementacao.
+Extrai assinaturas de funções e tipos SEM a implementação.
 
 ```bash
 ai-tool context Button
 ai-tool context src/hooks/useAuth.ts --format=json
-ai-tool context --area=auth   # Contexto consolidado de toda uma area
+ai-tool context --area=auth   # Contexto consolidado de toda uma área
 ```
 
 **Extrai:**
 - Imports com specifiers
 - Exports do arquivo
-- Funcoes com parametros e tipos de retorno
-- Interfaces, types e enums com definicoes
+- Funções com parâmetros e tipos de retorno
+- Interfaces, types e enums com definições
 
-Ideal para entender rapidamente a API publica de um arquivo.
+Ideal para entender rapidamente a API pública de um arquivo.
 
-**Contexto de Area** (`--area=<nome>`):
-- Tipos e interfaces da area
-- Hooks com parametros e retornos
-- Funcoes principais
+**Contexto de Área** (`--area=<nome>`):
+- Tipos e interfaces da área
+- Hooks com parâmetros e retornos
+- Funções principais
 - Componentes React
 - Services e stores
 - Uma chamada = entender toda a feature
 
-### `find` - Busca de Simbolos
+### `find` - Busca de Símbolos
 
-Busca simbolos no codigo (funcoes, tipos, componentes, hooks, constantes, triggers).
+Busca símbolos no código (funções, tipos, componentes, hooks, constantes, triggers).
 
 ```bash
-ai-tool find useAuth              # Definicao + usos
+ai-tool find useAuth              # Definição + usos
 ai-tool find User --type=type     # Busca apenas tipos
-ai-tool find login --area=auth    # Busca na area auth
-ai-tool find submit --def         # Apenas definicoes
-ai-tool find submit --refs        # Apenas referencias/usos
+ai-tool find login --area=auth    # Busca na área auth
+ai-tool find submit --def         # Apenas definições
+ai-tool find submit --refs        # Apenas referências/usos
 ai-tool find createUser --type=trigger  # Busca Cloud Functions
 ```
 
-**Tipos de simbolos:**
-- `function` - Funcoes e arrow functions (inclui triggers)
+**Tipos de símbolos:**
+- `function` - Funções e arrow functions (inclui triggers)
 - `type` - Types, interfaces e enums
-- `const` - Constantes e variaveis
-- `component` - Componentes React (funcao que retorna JSX)
-- `hook` - React hooks (funcao que comeca com `use`)
+- `const` - Constantes e variáveis
+- `component` - Componentes React (função que retorna JSX)
+- `hook` - React hooks (função que começa com `use`)
 - `trigger` - Firebase Cloud Functions (onCall, onDocumentCreated, etc.)
 - `all` - Todos os tipos (default)
 
-**Diferente de grep:** Entende o AST do TypeScript, encontra definicoes reais e onde sao usados.
+**Diferente de grep:** Entende o AST do TypeScript, encontra definições reais e onde são usados.
 
 ### `functions` - Firebase Cloud Functions
 
@@ -189,9 +189,9 @@ ai-tool functions --format=json
 - Identity: `beforeUserCreated`, `beforeUserSignedIn`, `beforeEmailSent`, `beforeSmsSent`
 - E mais: Crashlytics, Performance, Remote Config, Eventarc, Tasks, Test Lab
 
-### `areas` - Areas/Dominios Funcionais
+### `areas` - Áreas/Domínios Funcionais
 
-Lista todas as areas funcionais do projeto (auth, dashboard, stripe, etc).
+Lista todas as áreas funcionais do projeto (auth, dashboard, stripe, etc).
 
 ```bash
 ai-tool areas
@@ -199,13 +199,13 @@ ai-tool areas --format=json
 ```
 
 **Output:**
-- Lista de areas detectadas automaticamente
-- Contagem de arquivos por area
-- Distribuicao de categorias por area
+- Lista de áreas configuradas manualmente
+- Contagem de arquivos por área
+- Distribuição de categorias por área
 
-### `area` - Detalhe de uma Area
+### `area` - Detalhe de uma Área
 
-Mostra todos os arquivos de uma area especifica.
+Mostra todos os arquivos de uma área específica.
 
 ```bash
 ai-tool area auth
@@ -215,11 +215,11 @@ ai-tool area stripe --full          # Mostra todos os arquivos
 
 **Output:**
 - Arquivos agrupados por categoria
-- Descricao inferida de cada arquivo
+- Descrição inferida de cada arquivo
 
-### `areas init` - Configuracao de Areas
+### `areas init` - Configuração de Áreas
 
-Gera arquivo de configuracao editavel para areas.
+Gera arquivo de configuração editável para áreas.
 
 ```bash
 ai-tool areas init
@@ -227,15 +227,17 @@ ai-tool areas init --force  # Sobrescreve config existente
 ```
 
 Cria `.analyze/areas.config.json` com:
-- Areas detectadas automaticamente
-- Patterns glob para cada area
-- Keywords de deteccao
-- Descricoes manuais de arquivos
-- Padroes de ignore global
+- Template de áreas baseado no framework detectado
+- Patterns glob para cada área
+- Keywords de detecção
+- Descrições manuais de arquivos
+- Padrões de ignore global
 
-### Configuracao de Areas
+### Configuração de Áreas
 
-O arquivo `.analyze/areas.config.json` suporta:
+O arquivo `.analyze/areas.config.json` é a **fonte de verdade** para organização do projeto por domínios funcionais.
+
+**Estrutura completa:**
 
 ```json
 {
@@ -248,29 +250,57 @@ O arquivo `.analyze/areas.config.json` suporta:
   ],
   "areas": {
     "auth": {
-      "name": "Autenticacao",
-      "description": "Sistema de login e sessao",
+      "name": "Autenticação",
+      "description": "Sistema de login e sessão",
       "patterns": ["**/auth/**", "**/login/**"],
       "keywords": ["auth", "login", "session"]
+    },
+    "meus-pets": {
+      "name": "Meus Pets",
+      "description": "Gerenciamento de pets do usuário",
+      "patterns": [
+        "app/meus-pets/**",
+        "components/pets/**",
+        "hooks/usePets.*",
+        "services/petService.*"
+      ],
+      "keywords": ["pet", "animal"],
+      "exclude": ["components/pets/shared/**"]
     }
   },
   "descriptions": {
-    "src/hooks/useAuth.ts": "Hook principal de autenticacao"
+    "src/hooks/useAuth.ts": "Hook principal de autenticação",
+    "src/services/petService.ts": "Serviço de gerenciamento de pets"
   },
   "settings": {
-    "autoDetect": true,
-    "inferDescriptions": true
+    "autoDetect": false,
+    "inferDescriptions": true,
+    "groupByCategory": true
   }
 }
 ```
 
-| Campo | Descricao |
+| Campo | Descrição |
 |-------|-----------|
-| `ignore` | Padroes glob para ignorar arquivos/pastas globalmente |
-| `areas` | Definicao manual de areas com patterns e keywords |
-| `descriptions` | Descricoes manuais para arquivos especificos |
-| `settings.autoDetect` | Se `false`, usa apenas areas definidas manualmente |
-| `settings.inferDescriptions` | Infere descricoes automaticamente baseado no nome |
+| `ignore` | Padrões glob para ignorar arquivos/pastas globalmente |
+| `areas` | Definição manual de áreas com patterns e keywords |
+| `areas.<id>.name` | Nome amigável da área |
+| `areas.<id>.description` | Descrição do domínio de negócio |
+| `areas.<id>.patterns` | Padrões glob que identificam arquivos da área |
+| `areas.<id>.keywords` | Keywords no caminho do arquivo |
+| `areas.<id>.exclude` | Padrões para excluir arquivos específicos |
+| `descriptions` | Descrições manuais para arquivos específicos |
+| `settings.autoDetect` | **Sempre `false`** - configuração manual obrigatória |
+| `settings.inferDescriptions` | Infere descrições automaticamente baseado no nome |
+| `settings.groupByCategory` | Agrupa arquivos por categoria nos comandos |
+
+**Boas práticas:**
+
+- Ideal: 5-15 áreas (muitas áreas é difícil de navegar)
+- Use patterns para pastas: `"app/dashboard/**"`
+- Use keywords para arquivos espalhados: `["auth", "login"]`
+- Um arquivo pode pertencer a múltiplas áreas
+- Use `exclude` para remover arquivos específicos de uma área
 
 ## Servidor MCP
 
@@ -282,18 +312,18 @@ ai-tool --mcp
 
 **Tools expostas:**
 - `aitool_project_map` - Mapa do projeto (resumo compacto)
-- `aitool_dead_code` - Detecta codigo morto
-- `aitool_impact_analysis` - Analise de impacto antes de modificar
+- `aitool_dead_code` - Detecta código morto
+- `aitool_impact_analysis` - Análise de impacto antes de modificar
 - `aitool_suggest_reads` - Sugere arquivos para ler antes de editar
 - `aitool_file_context` - Extrai assinaturas de um arquivo
-- `aitool_list_areas` - Lista areas funcionais do projeto
-- `aitool_area_detail` - Arquivos de uma area especifica
-- `aitool_areas_init` - Gera config de areas
-- `aitool_area_context` - Contexto consolidado de toda uma area
-- `aitool_find` - Busca simbolos no codigo (definicao + usos)
+- `aitool_list_areas` - Lista áreas funcionais do projeto
+- `aitool_area_detail` - Arquivos de uma área específica
+- `aitool_areas_init` - Gera config de áreas
+- `aitool_area_context` - Contexto consolidado de toda uma área
+- `aitool_find` - Busca símbolos no código (definição + usos)
 - `aitool_list_functions` - Lista Cloud Functions Firebase
 
-### Configuracao Claude Code
+### Configuração Claude Code
 
 Adicione ao `.mcp.json` do projeto ou ao arquivo global `~/.claude/settings.json`:
 
@@ -308,7 +338,7 @@ Adicione ao `.mcp.json` do projeto ou ao arquivo global `~/.claude/settings.json
 }
 ```
 
-### Configuracao Claude Desktop
+### Configuração Claude Desktop
 
 Adicione ao `claude_desktop_config.json`:
 
@@ -326,86 +356,86 @@ Adicione ao `claude_desktop_config.json`:
 }
 ```
 
-## Uso Programatico
+## Uso Programático
 
 ```typescript
 import { map, dead, impact, suggest, context, areaContext, find, functions, areas, area, areasInit } from "@justmpm/ai-tool";
 
-// Mapa do projeto (resumo por padrao, full: true para lista completa)
+// Mapa do projeto (resumo por padrão, full: true para lista completa)
 const projectMap = await map({ format: "json" });
 const fullMap = await map({ format: "json", full: true });
 
-// Codigo morto
+// Código morto
 const deadCode = await dead({ format: "json" });
 
-// Analise de impacto
+// Análise de impacto
 const analysis = await impact("Button", { format: "json" });
 
-// Sugestao de leitura
+// Sugestão de leitura
 const suggestions = await suggest("Button", { limit: 5 });
 
 // Contexto do arquivo
 const fileContext = await context("Button", { format: "json" });
 
-// Contexto de uma area inteira
+// Contexto de uma área inteira
 const authContext = await areaContext("auth", { format: "json" });
 
-// Busca de simbolos
+// Busca de símbolos
 const symbolSearch = await find("useAuth", { type: "hook", area: "auth" });
 
 // Cloud Functions Firebase
 const cloudFunctions = await functions({ trigger: "onCall" });
 
-// Areas funcionais
+// Áreas funcionais
 const projectAreas = await areas({ format: "json" });
 
-// Detalhe de uma area
+// Detalhe de uma área
 const authArea = await area("auth", { type: "hook" });
 
-// Gerar config de areas
+// Gerar config de áreas
 await areasInit({ force: false });
 ```
 
-## Opcoes
+## Opções
 
-| Opcao | Descricao | Default |
+| Opção | Descrição | Default |
 |-------|-----------|---------|
-| `--format=text\|json` | Formato de saida | `text` |
-| `--cwd=<path>` | Diretorio do projeto | `process.cwd()` |
+| `--format=text\|json` | Formato de saída | `text` |
+| `--cwd=<path>` | Diretório do projeto | `process.cwd()` |
 | `--no-cache` | Ignora cache | `false` |
 | `--full` | Lista completa (`map`: arquivos, `area`: todos) | `false` |
-| `--fix` | Remove codigo morto (so `dead`) | `false` |
-| `--limit=<n>` | Limite de sugestoes (so `suggest`) | `10` |
-| `--type=<cat>` | Filtra por categoria (`area`) ou tipo de simbolo (`find`) | - |
-| `--area=<nome>` | Filtra por area (`context`, `find`) | - |
-| `--def` | Mostra apenas definicoes (so `find`) | `false` |
-| `--refs` | Mostra apenas referencias/usos (so `find`) | `false` |
+| `--fix` | Remove código morto (só `dead`) | `false` |
+| `--limit=<n>` | Limite de sugestões (só `suggest`) | `10` |
+| `--type=<cat>` | Filtra por categoria (`area`) ou tipo de símbolo (`find`) | - |
+| `--area=<nome>` | Filtra por área (`context`, `find`) | - |
+| `--def` | Mostra apenas definições (só `find`) | `false` |
+| `--refs` | Mostra apenas referências/usos (só `find`) | `false` |
 | `--mcp` | Inicia servidor MCP | - |
 
 ## Categorias de Arquivos
 
-| Categoria | Descricao |
+| Categoria | Descrição |
 |-----------|-----------|
-| `page` | Paginas (Next.js, etc.) |
+| `page` | Páginas (Next.js, etc.) |
 | `layout` | Layouts |
 | `route` | Rotas de API |
 | `component` | Componentes React/Vue |
 | `hook` | React Hooks |
-| `service` | Servicos/API |
+| `service` | Serviços/API |
 | `store` | Estado global |
-| `util` | Utilitarios |
+| `util` | Utilitários |
 | `type` | Tipos TypeScript |
-| `config` | Configuracoes |
+| `config` | Configurações |
 | `test` | Testes |
 | `cloud-function` | Firebase Cloud Functions |
 | `other` | Outros |
 
 ## Cache
 
-Resultados sao salvos em `.analyze/` para acelerar execucoes futuras.
+Resultados são salvos em `.analyze/` para acelerar execuções futuras.
 
-- Cache e invalidado automaticamente quando arquivos mudam
-- Use `--no-cache` para forcar regeneracao
+- Cache é invalidado automaticamente quando arquivos mudam
+- Use `--no-cache` para forcar regeneração
 - Adicione `.analyze/` ao `.gitignore`
 
 ## Requisitos
@@ -413,12 +443,12 @@ Resultados sao salvos em `.analyze/` para acelerar execucoes futuras.
 - Node.js >= 18.0.0
 - Projeto TypeScript/JavaScript
 
-## Creditos
+## Créditos
 
-- [Skott](https://github.com/antoine-coulon/skott) - Analise de dependencias
-- [Knip](https://knip.dev) - Deteccao de codigo morto
-- [ts-morph](https://ts-morph.com) - Analise AST
+- [Skott](https://github.com/antoine-coulon/skott) - Análise de dependências
+- [Knip](https://knip.dev) - Detecção de código morto
+- [ts-morph](https://ts-morph.com) - Análise AST
 
-## Licenca
+## Licença
 
 MIT - [Koda AI Studio](https://kodaai.app)