@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/framework/skills/level-1-workflows/phase-codebase-analysis.md

@@ -0,0 +1,182 @@
+---
+name: phase-codebase-analysis
+description: >
+  MORPH-SPEC sub-phase of Design. Analyzes existing codebase patterns, architecture, and conventions before writing the spec. Called automatically at the start of Design phase.
+user-invocable: false
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# MORPH Codebase Analysis - Sub-fase de DESIGN
+
+> INTERNAL: Automation skill for schema analysis step within Phase 2 (Design).
+> Called by `phase-design.md` Passo 2. Not a standalone user command.
+
+Automatiza a análise de código existente para gerar `schema-analysis.md` com dados reais do banco/código.
+
+## Pré-requisitos
+
+- [ ] FASE 1 (Setup) concluída
+- [ ] Feature tem `proposal.md` aprovado
+- [ ] Contexto do projeto carregado (stack, agentes)
+
+## Ferramentas Recomendadas
+
+> **Ref:** `framework/skills/level-0-meta/tool-usage-guide.md` para guia completo.
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` para referência MCP.
+
+| Ação | Ferramenta | Alternativa |
+|------|------------|-------------|
+| Listar tabelas do banco | **Supabase MCP** `list_tables()` | **Grep** `.from(` no código |
+| Obter schema de tabela | **Supabase MCP** `get_table_schema()` | **Read** type definitions |
+| Obter relacionamentos FK | **Supabase MCP** `get_relationships()` | **Grep** JOIN/FK patterns |
+| Obter políticas RLS | **Supabase MCP** `query()` | **Read** policy files |
+| Encontrar queries no código | **Grep** `\.from\(` em `*.ts,*.tsx,*.js,*.cs` | — |
+| Encontrar type definitions | **Glob** `src/**/types/**/*.ts` ou `**/Entities/**/*.cs` | — |
+| Ler arquivos encontrados | **Read** cada arquivo | — |
+| Análise multi-arquivo complexa | **Task** (subagent Explore) | Read individual |
+| Gerar schema-analysis.md | **Write** usando template | **Bash** template render |
+
+**MCPs desta fase:** Supabase (schema — **PRIORITÁRIO**), Database MCPs genéricos.
+
+---
+
+## Workflow Automatizado
+
+### Passo 1: Detectar Método de Análise
+
+```
+SE MCP Supabase disponível:
+  → Usar Método A (MCP direto)
+SE MCP Database disponível:
+  → Usar Método A adaptado
+SENÃO:
+  → Usar Método B (análise estática de código)
+```
+
+### Passo 2A: Método MCP (Preferencial)
+
+**Ferramentas:** Supabase MCP
+
+```javascript
+// 1. Listar todas as tabelas
+const tables = await mcp__supabase__list_tables();
+
+// 2. Para cada tabela relevante à feature:
+for (const table of relevantTables) {
+  // 2a. Schema completo
+  const schema = await mcp__supabase__get_table_schema({ table: table.name });
+  // → column_name, data_type, is_nullable, column_default
+
+  // 2b. Relacionamentos
+  const rels = await mcp__supabase__get_relationships({ table: table.name });
+  // → foreign_table, foreign_column, constraint_type
+
+  // 2c. Indexes
+  const indexes = await mcp__supabase__query({
+    query: `SELECT indexname, indexdef FROM pg_indexes WHERE tablename = '${table.name}'`
+  });
+
+  // 2d. RLS policies (segurança)
+  const policies = await mcp__supabase__query({
+    query: `SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = '${table.name}'`
+  });
+}
+```
+
+### Passo 2B: Método Análise Estática (Fallback)
+
+**Ferramentas:** Grep, Glob, Read, Task (subagent para projetos grandes)
+
+**Fase B1: Encontrar Queries**
+
+```
+Grep: "\.from\(|\.select\(|SELECT |supabase\.|context\.|dbContext\.|DbSet<"
+Type: ts,tsx,js,jsx,cs
+Output: files_with_matches
+```
+
+**Fase B2: Ler Arquivos de Query**
+
+Para cada arquivo encontrado, use **Read** para extrair:
+- Nomes de tabelas: `from('leads')`, `DbSet<Lead>`, `FROM leads`
+- Nomes de colunas: `.select('fullname, phonenumber')`, `l.FullName`
+- Tipos de dados: TypeScript interfaces, C# DTOs
+- Relacionamentos: JOIN clauses, navigation properties
+
+**Fase B3: Encontrar Type Definitions**
+
+```
+# TypeScript/JavaScript:
+Glob: "src/**/types/**/*.ts"
+Glob: "src/**/*.d.ts"
+Glob: "src/**/interfaces/*.ts"
+
+# .NET:
+Glob: "**/*Dto.cs"
+Glob: "**/Entities/**/*.cs"
+Glob: "**/Models/**/*.cs"
+```
+
+**Fase B4: Quando usar Task (subagent)**
+
+Use Task subagent **APENAS** quando:
+- Projeto tem 20+ arquivos de query
+- Múltiplos padrões de acesso a dados (Supabase + EF Core + raw SQL)
+- Análise precisa de contexto cruzado entre muitos arquivos
+
+Não use Task subagent quando:
+- Projeto tem < 10 arquivos de query (Read direto é mais rápido)
+- Padrão de acesso a dados é uniforme (só Supabase OU só EF Core)
+
+### Passo 3: Mapear Inconsistências
+
+Crie um mapa de:
+
+| Frontend/Código | Banco de Dados | Tipo | Problema |
+|----------------|----------------|------|----------|
+| user.name | users.fullname | string | ❌ MISMATCH |
+| lead.phone | leads.phonenumber | string | ❌ MISMATCH |
+| order.metadata | orders.metadata | JSONB | ⚠️ Type complex |
+
+### Passo 4: Gerar `schema-analysis.md`
+
+Use o template em `framework/templates/docs/schema-analysis.md`:
+
+```bash
+npx morph-spec template render docs/schema-analysis \
+  .morph/features/{feature-name}/1-design/schema-analysis.md \
+  '{ "FEATURE_NAME": "{feature-name}", "DATE": "..." }'
+```
+
+OU use **Write** tool para criar diretamente com os dados coletados.
+
+### Passo 5: Atualizar State
+
+```bash
+npx morph-spec state mark-output {feature-name} schema-analysis
+```
+
+---
+
+## Outputs
+
+- `.morph/features/{feature}/1-design/schema-analysis.md`
+- State atualizado com output `schemaAnalysis`
+
+## CHECKPOINT
+
+Antes de prosseguir para contracts.cs, apresente ao usuário:
+
+- [ ] Analisei {N} tabelas
+- [ ] Encontrei {N} field name mismatches
+- [ ] Encontrei {N} type mismatches
+- [ ] Mapeei {N} relacionamentos
+- [ ] `schema-analysis.md` criado
+
+**Perguntas obrigatórias:**
+1. "O schema analysis está correto?"
+2. "Posso gerar contracts.cs com base nesse schema real?"
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*