---
name: mapear-codigo-fonte
scope: global
description: >
  Guia operacional para mapear, navegar e compreender a estrutura de um monorepo TypeScript.
---

# Skill: Mapear Código-Fonte de Monorepo TypeScript

Use esta skill ao iniciar trabalho em um monorepo desconhecido, ao onboardar em novo projeto, ou quando precisar localizar rapidamente onde uma funcionalidade vive no código.

---

## PASSO 1 — Identificar a Raiz e o Gerenciador de Pacotes

Localize os arquivos que definem a estratégia de monorepo:

```bash
# Identificar o gerenciador e workspace config
ls -la package.json pnpm-workspace.yaml lerna.json turbo.json nx.json tsconfig.base.json 2>/dev/null
```

Elementos a extrair:

- **Gerenciador**: `pnpm` (workspaces em `pnpm-workspace.yaml`), `npm/yarn` (workspaces em `package.json`), ou `nx`/`turbo`
- **Pacotes compartilhados**: diretórios listados em `packages:` ou `workspaces:`
- **Apps/serviços**: diretórios de aplicações deployáveis
- **TSConfig base**: herança de configuração TypeScript entre pacotes

---

## PASSO 2 — Mapear a Árvore de Pacotes

```bash
# Listar todos os pacotes do workspace com nomes e caminhos
# pnpm
pnpm ls --depth -1 -r --json 2>/dev/null | jq '.[].name'

# Alternativa genérica: encontrar todos os package.json
fd package.json --max-depth 3 --type f --exec sh -c 'echo "$(dirname {}): $(jq -r .name {})"'
```

Organizar os pacotes em categorias:

| Categoria | Padrão de nome | Exemplo |
|-----------|---------------|---------|
| **Libs compartilhadas** | `@org/common`, `*-comuns`, `*-shared` | Tipos, utils, schemas |
| **Backend** | `*-back`, `*-api`, `*-server` | Serviços Node/Express/Fastify |
| **Frontend** | `*-front`, `*-web`, `*-app` | Apps Vue/React/Angular |
| **Ferramentas** | `*-cli`, `*-scripts`, `*-tools` | Scripts de build, migrations |
| **Configs** | `*-config`, `*-eslint-config` | Configs compartilhadas |

---

## PASSO 3 — Mapear Dependências Internas

Identificar o grafo de dependências entre pacotes internos:

```bash
# Para cada package.json, listar deps internas (que apontam para workspace:)
rg '"workspace:' --include='package.json' -l | while read f; do
  echo "=== $(jq -r .name "$f") ==="
  jq -r '.dependencies // {} | to_entries[] | select(.value | startswith("workspace:")) | .key' "$f"
  jq -r '.devDependencies // {} | to_entries[] | select(.value | startswith("workspace:")) | .key' "$f"
done
```

Anotar:

- Quais pacotes são **folha** (não dependem de outros internos)
- Quais são **raiz** (ninguém depende deles — geralmente apps)
- Quais são **núcleo** (muitos dependem deles — geralmente libs compartilhadas)

---

## PASSO 4 — Mapear Arquitetura de Cada Pacote

Para cada pacote relevante, identificar a estrutura interna:

```bash
# Visão geral rápida (2 níveis de profundidade)
eza --tree --level=2 --icons --group-directories-first <caminho-do-pacote>/src/
# ou
tree -L 2 -I node_modules <caminho-do-pacote>/src/
```

Padrões comuns a procurar:

| Diretório | Responsabilidade típica |
|-----------|----------------------|
| `src/routes/` ou `src/api/` | Endpoints/rotas HTTP |
| `src/services/` | Lógica de negócio |
| `src/models/` ou `src/entities/` | Modelos de dados |
| `src/utils/` ou `src/helpers/` | Funções utilitárias |
| `src/types/` ou `src/typings/` | Definições de tipos TS |
| `src/schemas/` | Schemas de validação (Zod, Joi) |
| `src/migrations/` | Migrações de banco |
| `src/components/` | Componentes de UI (frontend) |
| `src/composables/` ou `src/hooks/` | Lógica reutilizável (Vue/React) |
| `src/stores/` | Gerenciamento de estado |

---

## PASSO 5 — Identificar Pontos de Entrada e Exportações

```bash
# Encontrar exports públicos de cada pacote
rg "export " --include='index.ts' --include='index.tsx' -l

# Encontrar entry points no package.json
fd package.json --max-depth 3 --type f --exec sh -c 'echo "$(jq -r .name {}):" && jq "{main, module, types, exports}" {}'
```

---

## PASSO 6 — Documentar o Mapa

Produzir um resumo estruturado com:

```markdown
# Mapa do Monorepo: <nome>

## Gerenciador: pnpm | npm | yarn
## Build System: tsc | turbo | nx

## Pacotes

### Libs Compartilhadas
- `@org/types` → tipos compartilhados (depende de: nenhum)
- `@org/utils` → funções utilitárias (depende de: @org/types)

### Aplicações
- `@org/api` → backend Express (depende de: @org/types, @org/utils)
- `@org/web` → frontend Vue (depende de: @org/types)

## Fluxo de dados
Descrever como os dados fluem entre pacotes.

## Scripts importantes
- `pnpm build` → Build de todos os pacotes
- `pnpm dev` → Inicia dev server
- `pnpm test` → Roda testes
```

---

## Checklist Final

- [ ] O gerenciador de pacotes e workspace strategy estão identificados?
- [ ] Todos os pacotes foram categorizados (lib/app/tool)?
- [ ] O grafo de dependências internas foi mapeado?
- [ ] Os pontos de entrada de cada pacote estão claros?
- [ ] A arquitetura interna dos pacotes principais foi documentada?
- [ ] Scripts de build/dev/test foram identificados?

## Referências

- Rules: `.agent/rules/typescript-sem-any.global.md`
- Workflow: `.agent/workflows/documentar-codigo.global.md`