160 lines
5.1 KiB
Markdown
160 lines
5.1 KiB
Markdown
---
|
|
name: mapear-codigo-fonte
|
|
scope: global
|
|
updatedAt: "2026-06-01"
|
|
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: `global/rules/typescript-sem-any.md`
|
|
- Workflow: `global/workflows/otimizar-codigos.md`
|