@girardelli/architect 2.2.0 → 5.0.0

package/src/agent-generator/templates/core/architecture-rules.ts

@@ -0,0 +1,287 @@
+import { TemplateContext } from '../../types.js';
+
+/**
+ * Generates 01-architecture.md — layer rules, dependency direction,
+ * module patterns, and anti-pattern prevention.
+ */
+export function generateArchitectureRules(ctx: TemplateContext): string {
+  const { stack, projectName, report, config } = ctx;
+  const layerRules = buildLayerRules(ctx);
+  const modulePattern = buildModulePattern(ctx);
+
+  return `---
+antigravity:
+  trigger: 'always_on'
+  globs: ['**/*']
+  description: 'Regras de arquitetura para ${projectName}'
+  priority: HIGH
+---
+
+# 🏗️ Regras de Arquitetura — ${projectName}
+
+> **Separação de camadas, direção de dependências, e padrões de módulo.**
+
+---
+
+## 📐 Camadas Arquiteturais
+
+${layerRules}
+
+### Direção de Dependência (OBRIGATÓRIA)
+
+\`\`\`
+UI / Controllers  →  Services  →  Repositories / Data  →  Entities
+       ↓                ↓                 ↓
+   (pode usar)     (pode usar)      (pode usar)
+   Services        Repositories     Entities
+   DTOs            Entities         Value Objects
+                   DTOs
+
+⚠️  NUNCA:
+   Entity → Controller
+   Repository → Controller
+   Service → Controller
+   Data Layer → UI Layer
+\`\`\`
+
+### Regra de Ouro das Camadas
+
+\`\`\`
+╔══════════════════════════════════════════════════════╗
+║  Uma camada SÓ pode depender de camadas ABAIXO.     ║
+║  NUNCA de camadas acima ou da mesma camada lateral. ║
+╚══════════════════════════════════════════════════════╝
+\`\`\`
+
+---
+
+## 📦 Padrão de Módulo
+
+${modulePattern}
+
+---
+
+## 🚫 Anti-Patterns a Prevenir
+
+### God Class (> 500 linhas ou > 10 métodos)
+\`\`\`
+❌ PROIBIDO: Classe com múltiplas responsabilidades
+✅ CORRETO: Extrair em classes menores com responsabilidade única
+
+Se um arquivo ultrapassar 500 linhas:
+1. PARAR
+2. Identificar responsabilidades distintas
+3. Extrair em módulos separados
+4. Atualizar imports
+\`\`\`
+
+### Circular Dependencies
+\`\`\`
+❌ PROIBIDO: A importa B, B importa A
+✅ CORRETO: Extrair interface comum ou usar event/mediator
+
+Detecção:
+$ npx madge --circular src/
+$ architect anti-patterns .
+\`\`\`
+
+### Leaky Abstractions
+\`\`\`
+❌ PROIBIDO: Service expondo detalhes de implementação
+✅ CORRETO: Interface define contrato, implementação é encapsulada
+
+Exemplos:
+- Service retornando QueryBuilder → ERRADO (vaza ORM)
+- Service retornando DTO → CORRETO (abstrai)
+- Controller acessando Entity → ERRADO (vaza modelo)
+- Controller acessando DTO → CORRETO (contrato)
+\`\`\`
+
+### Feature Envy
+\`\`\`
+❌ PROIBIDO: Método que usa mais atributos de outra classe que da própria
+✅ CORRETO: Mover método para a classe que possui os dados
+\`\`\`
+
+### Shotgun Surgery
+\`\`\`
+❌ PROIBIDO: Mudança em 1 feature exige alterar 10+ arquivos
+✅ CORRETO: Agrupar código relacionado no mesmo módulo
+
+Se uma mudança toca > 5 arquivos:
+1. PARAR
+2. Reavaliar se o código está no lugar certo
+3. Considerar refatoração preventiva
+\`\`\`
+
+---
+
+## 🏛️ Princípios Arquiteturais
+
+### DDD (Domain-Driven Design) — Quando Aplicável
+\`\`\`
+Entities:       Objetos com identidade (ID único)
+Value Objects:  Objetos sem identidade (imutáveis)
+Aggregates:     Cluster de entidades com root
+Repositories:   Acesso a dados de Aggregates
+Services:       Lógica que não pertence a nenhuma entidade
+\`\`\`
+
+### Clean Architecture
+\`\`\`
+Camada mais interna: Entities (regras de negócio)
+Camada média:        Use Cases / Services (lógica de aplicação)
+Camada externa:      Controllers, Gateways, Presenters (I/O)
+
+Dependência: SEMPRE de fora para dentro, NUNCA o contrário.
+\`\`\`
+
+### Event-Driven — Quando Aplicável
+\`\`\`
+Usar eventos quando:
+- Desacoplamento entre módulos é necessário
+- Processamento assíncrono é aceitável
+- Múltiplos handlers para um mesmo trigger
+
+NÃO usar eventos quando:
+- Resposta síncrona é necessária
+- Transação atômica é obrigatória
+- Ordem de execução importa
+\`\`\`
+
+---
+
+## 📊 Anti-Patterns Atuais do Projeto
+
+${report.antiPatterns.length > 0
+    ? report.antiPatterns.map(a =>
+      `- **${a.name}** (${a.severity}) em \`${a.location}\` — ${a.suggestion}`
+    ).join('\n')
+    : '✅ Nenhum anti-pattern detectado. Manter assim.'}
+
+Score atual: **${report.score.overall}/100** | Meta: **${Math.min(100, report.score.overall + 10)}/100**
+
+---
+
+## ✅ Checklist de Arquitetura
+
+Antes de criar qualquer módulo novo:
+
+\`\`\`
+□ Camada correta? (Controller vs Service vs Repository vs Entity)
+□ Direção de dependência respeitada? (nunca de baixo para cima)
+□ Módulo coeso? (tudo relacionado junto)
+□ Sem circular dependency?
+□ Sem God Class? (< 500 linhas, < 10 métodos)
+□ Interface/abstração antes de implementação?
+□ DTOs para comunicação entre camadas?
+□ Testes por camada? (unit para service, integration para controller)
+\`\`\`
+
+---
+
+**Gerado por Architect v3.1 · Score: ${report.score.overall}/100**
+`;
+}
+
+function buildLayerRules(ctx: TemplateContext): string {
+  const { stack } = ctx;
+
+  if (stack.frameworks.includes('NestJS')) {
+    return `| Camada | Responsabilidade | Padrão NestJS |
+|--------|-----------------|---------------|
+| **API** (Controllers) | Routing, validação de request, response shaping | \`*.controller.ts\` + \`@Controller()\` |
+| **Service** | Lógica de negócio, orquestração | \`*.service.ts\` + \`@Injectable()\` |
+| **Data** (Repository) | Acesso a dados, queries | \`*.repository.ts\` ou TypeORM Repository |
+| **Entity** | Modelo de domínio | \`*.entity.ts\` + \`@Entity()\` |
+| **DTO** | Contratos de request/response | \`*.dto.ts\` + class-validator |
+| **Guard** | Autenticação/Autorização | \`*.guard.ts\` + \`@UseGuards()\` |
+| **Pipe** | Validação/transformação | \`*.pipe.ts\` + \`@UsePipes()\` |`;
+  }
+
+  if (stack.frameworks.includes('Django') || stack.frameworks.includes('Flask') || stack.frameworks.includes('FastAPI')) {
+    return `| Camada | Responsabilidade | Padrão Python |
+|--------|-----------------|---------------|
+| **API** (Views/Routes) | Routing, serialização | views.py / routes.py |
+| **Service** | Lógica de negócio | services.py |
+| **Data** (Repository/ORM) | Acesso a dados | models.py + managers |
+| **Schema** | Validação I/O | serializers.py / schemas.py |
+| **Tasks** | Processamento assíncrono | tasks.py (Celery) |`;
+  }
+
+  if (stack.frameworks.includes('Angular')) {
+    return `| Camada | Responsabilidade | Padrão Angular |
+|--------|-----------------|----------------|
+| **Component** | UI rendering, user events | \`*.component.ts\` |
+| **Service** | Lógica, API calls, state | \`*.service.ts\` + \`@Injectable()\` |
+| **Model** | Interfaces/types | \`*.model.ts\` / \`*.interface.ts\` |
+| **Guard** | Route protection | \`*.guard.ts\` + \`canActivate\` |
+| **Interceptor** | HTTP middleware | \`*.interceptor.ts\` |
+| **Pipe** | Data transformation | \`*.pipe.ts\` |`;
+  }
+
+  // Generic
+  return `| Camada | Responsabilidade | Padrão |
+|--------|-----------------|--------|
+| **API / Controllers** | Routing, validação HTTP | controllers/ |
+| **Service** | Lógica de negócio | services/ |
+| **Data / Repository** | Acesso a dados | repositories/ |
+| **Entity / Model** | Modelo de domínio | entities/ ou models/ |
+| **DTO / Schema** | Contratos I/O | dto/ ou schemas/ |`;
+}
+
+function buildModulePattern(ctx: TemplateContext): string {
+  const { stack } = ctx;
+  const ext = stack.primary === 'Python' ? 'py' : stack.primary === 'Dart' ? 'dart' : 'ts';
+
+  if (stack.frameworks.includes('NestJS')) {
+    return `\`\`\`
+src/modules/[nome-do-modulo]/
+├── [nome].module.ts           → NestJS Module (imports, providers, exports)
+├── [nome].controller.ts       → HTTP endpoints
+├── [nome].controller.spec.ts  → Testes do controller
+├── [nome].service.ts          → Lógica de negócio
+├── [nome].service.spec.ts     → Testes do service
+├── dto/
+│   ├── create-[nome].dto.ts   → Request de criação
+│   ├── update-[nome].dto.ts   → Request de atualização
+│   └── [nome]-response.dto.ts → Response shape
+├── entities/
+│   └── [nome].entity.ts       → TypeORM entity
+├── guards/                    → Guards específicos (se houver)
+└── interfaces/                → Interfaces/types do módulo
+\`\`\``;
+  }
+
+  if (stack.frameworks.includes('Angular')) {
+    return `\`\`\`
+src/app/modules/[nome-do-modulo]/
+├── [nome].module.ts                → Angular Module
+├── [nome]-routing.module.ts        → Routes
+├── components/
+│   ├── [nome]-list/
+│   │   ├── [nome]-list.component.ts
+│   │   ├── [nome]-list.component.html
+│   │   ├── [nome]-list.component.scss
+│   │   └── [nome]-list.component.spec.ts
+│   └── [nome]-form/
+│       └── ...
+├── services/
+│   ├── [nome].service.ts
+│   └── [nome].service.spec.ts
+├── models/
+│   └── [nome].model.ts
+└── guards/
+\`\`\``;
+  }
+
+  return `\`\`\`
+src/modules/[nome-do-modulo]/
+├── [nome].module.${ext}
+├── [nome].controller.${ext}  → Endpoints / API
+├── [nome].service.${ext}     → Lógica de negócio
+├── dto/                       → Request/Response shapes
+├── entities/                  → Modelos de domínio
+└── __tests__/                 → Testes do módulo
+\`\`\``;
+}

package/src/agent-generator/templates/core/general-rules.ts

@@ -0,0 +1,306 @@
+import { TemplateContext } from '../../types.js';
+import { getEnriched } from '../template-helpers.js';
+
+/**
+ * Generates enterprise-grade 00-general.md rules.
+ * Golden rules, git flow, project identity, naming conventions,
+ * diagnostic requirements, forbidden actions, compliance checklist.
+ */
+export function generateGeneralRules(ctx: TemplateContext): string {
+  const { stack, projectName, stackLabel, config, report } = ctx;
+  const enriched = getEnriched(ctx);
+  const namingConventions = buildNamingConventions(ctx);
+
+  // Stack-aware forbidden type actions
+  const langs = stack.languages.map((l) => l.toLowerCase());
+  let typeProhibitions = `❌ any (TypeScript) sem justificativa em comentário
+❌ @ts-ignore / type: ignore sem justificativa`;
+
+  if (langs.includes('python')) {
+    typeProhibitions = `❌ type: ignore sem justificativa em comentário
+❌ # noqa sem justificativa
+❌ Any (typing) sem justificativa em comentário`;
+  } else if (langs.includes('dart')) {
+    typeProhibitions = `❌ dynamic sem justificativa em comentário
+❌ // ignore: sem justificativa
+❌ as dynamic sem type-check`;
+  } else if (langs.includes('java') || langs.includes('kotlin')) {
+    typeProhibitions = `❌ @SuppressWarnings sem justificativa em comentário
+❌ Object onde tipo específico é possível
+❌ Raw types sem justificativa`;
+  } else if (langs.includes('go')) {
+    typeProhibitions = `❌ interface{}/any sem justificativa em comentário
+❌ //nolint sem justificativa
+❌ _ (blank identifier) para erros sem tratamento`;
+  } else if (langs.includes('rust')) {
+    typeProhibitions = `❌ unwrap() em código de produção sem justificativa
+❌ #[allow(...)] sem justificativa em comentário
+❌ unsafe sem revisão e justificativa`;
+  }
+
+  return `---
+antigravity:
+  trigger: 'always_on'
+  globs: ['**/*']
+  description: 'Regras gerais invioláveis para ${projectName}'
+  priority: CRITICAL
+---
+
+# 📜 Regras Gerais — ${projectName}
+
+> **Estas regras são INVIOLÁVEIS. Não há exceção.**
+
+---
+
+## 🏆 Regras de Ouro
+
+\`\`\`
+╔══════════════════════════════════════════════════════════════╗
+║                    9 REGRAS DE OURO                         ║
+║                                                              ║
+${config.goldenRules.map((r, i) => `║  ${i + 1}. ${r.padEnd(55)}║`).join('\n')}
+║                                                              ║
+║  ⚠️  Violar qualquer regra = PARAR e RECOMEÇAR              ║
+╚══════════════════════════════════════════════════════════════╝
+\`\`\`
+
+---
+
+## 🏢 Identidade do Projeto
+
+| Item | Valor |
+|------|-------|
+| **Nome** | ${projectName} |
+| **Stack** | ${stackLabel} |
+| **Score** | ${report.score.overall}/100 |
+| **Linguagens** | ${stack.languages.join(', ')} |
+| **Frameworks** | ${enriched.detectedFrameworks?.filter((f: any) => f.category === 'web' || f.category === 'orm').map((f: any) => `${f.name}${f.version ? ` v${f.version}` : ''}`).join(', ') || stack.frameworks.join(', ') || 'Nenhum detectado'} |
+| **Cobertura Mínima** | ${config.coverageMinimum}% |
+| **Score Mínimo** | ${config.scoreThreshold}/100 |
+
+---
+
+## 🔄 Fluxo Completo (Qualquer Ação)
+
+\`\`\`
+REQUISIÇÃO
+    │
+    ▼
+LEITURA OBRIGATÓRIA (INDEX.md → 00-general → PREFLIGHT)
+    │
+    ▼
+DIAGNÓSTICO (entender ANTES de agir)
+    │
+    ▼
+ARTEFATOS (mockup → user story → arch → tasks → BDD → TDD)
+    │
+    ▼
+APROVAÇÃO HUMANA (/approved)
+    │
+    ▼
+IMPLEMENTAÇÃO (Backend → Integration Doc → Frontend/App)
+    │
+    ▼
+QUALITY GATES (build + test + coverage + score)
+    │
+    ▼
+CODE REVIEW
+    │
+    ▼
+MERGE (via PR, nunca direto)
+\`\`\`
+
+---
+
+## 🌿 Git Flow
+
+### Branch Naming
+
+| Tipo | Padrão | Exemplo |
+|------|--------|---------|
+| Feature | \`feature/[ticket]-[descricao]\` | \`feature/PROJ-123-cancelled-tab\` |
+| Bug fix | \`fix/[ticket]-[descricao]\` | \`fix/PROJ-456-null-balance\` |
+| Hotfix | \`hotfix/[descricao]\` | \`hotfix/payment-crash\` |
+| Refactor | \`refactor/[descricao]\` | \`refactor/extract-auth-service\` |
+
+### Commit Messages (Conventional Commits)
+
+\`\`\`
+feat: add cancelled refuelings tab
+fix: prevent null balance on payment
+refactor: extract auth service from user module
+docs: update API documentation for v2
+test: add integration tests for payment flow
+chore: upgrade dependencies
+\`\`\`
+
+### Cenários de Git Flow
+
+**Cenário A: Feature nova**
+\`\`\`
+git checkout develop
+git pull origin develop
+git checkout -b feature/PROJ-XXX-nome
+# ... implementar ...
+git add [arquivos específicos]
+git commit -m "feat: [descrição]"
+git push -u origin feature/PROJ-XXX-nome
+# Criar PR para develop
+\`\`\`
+
+**Cenário B: Bug fix**
+\`\`\`
+git checkout develop
+git pull origin develop
+git checkout -b fix/PROJ-XXX-descricao
+# ... corrigir ...
+git add [arquivos específicos]
+git commit -m "fix: [descrição]"
+git push -u origin fix/PROJ-XXX-descricao
+# Criar PR para develop
+\`\`\`
+
+**Cenário C: Hotfix em produção**
+\`\`\`
+git checkout main
+git pull origin main
+git checkout -b hotfix/descricao
+# ... corrigir ...
+git add [arquivos específicos]
+git commit -m "fix: [descrição] (hotfix)"
+git push -u origin hotfix/descricao
+# Criar PR para main E develop
+\`\`\`
+
+---
+
+## 📝 Naming Conventions
+
+${namingConventions}
+
+---
+
+## 🔍 Diagnóstico Obrigatório
+
+> **Antes de QUALQUER implementação, execute este diagnóstico.**
+
+\`\`\`bash
+# 1. Entender a estrutura
+ls -la src/
+find src/ -name "*.${stack.primary === 'Python' ? 'py' : stack.primary === 'Dart' ? 'dart' : 'ts'}" | head -30
+
+# 2. Entender as dependências do módulo
+grep -rn "import" --include="*.${stack.primary === 'Python' ? 'py' : 'ts'}" src/[modulo]/ | head -20
+
+# 3. Testes existentes
+find . -name "*.test.*" -o -name "*.spec.*" -o -name "*_test.*" | wc -l
+
+# 4. Score atual
+npx @girardelli/architect score .
+
+# 5. Anti-patterns
+npx @girardelli/architect anti-patterns .
+\`\`\`
+
+---
+
+## ❌ Ações PROIBIDAS
+
+\`\`\`
+❌ Commitar direto em main ou develop
+❌ Push --force sem aprovação explícita
+❌ Merge sem code review
+❌ Código sem testes
+❌ Ignorar falhas de build/test
+❌ Hardcodar secrets, tokens, senhas
+❌ console.log / print() em produção
+${typeProhibitions}
+❌ Testes com .skip() permanente
+❌ Copiar/colar código (extrair abstração)
+❌ Alterar mais de 10 arquivos sem reavaliar escopo
+❌ Implementar sem artefatos aprovados (mockup, US, BDD, TDD)
+❌ Decidir arquitetura sem consultar o humano
+❌ Refatorar código alheio ao escopo da task
+\`\`\`
+
+---
+
+## ✅ Checklist de Compliance (Regras de Ouro)
+
+Antes de marcar QUALQUER tarefa como "done":
+
+\`\`\`
+□ Regra 1: Git Flow completo (branch + PR + review)?
+□ Regra 2: Arquitetura documentada (C4 se nova feature)?
+□ Regra 3: BDD escrito antes do código?
+□ Regra 4: TDD aplicado (RED → GREEN → REFACTOR)?
+□ Regra 5: Diagnóstico feito antes de codar?
+□ Regra 6: Mockup aprovado (se tem UI)?
+□ Regra 7: Decisões validadas com humano?
+□ Regra 8: Qualidade > Velocidade (sem atalhos)?
+□ Regra 9: Apenas código (sem abrir browser, sem screenshots)?
+\`\`\`
+
+---
+
+**Gerado por Architect v3.1 · Score: ${report.score.overall}/100 · ${new Date().toISOString().split('T')[0]}**
+`;
+}
+
+function buildNamingConventions(ctx: TemplateContext): string {
+  const { stack } = ctx;
+  const lang = stack.primary;
+
+  if (lang === 'Python') {
+    return `| Item | Padrão | Exemplo |
+|------|--------|---------|
+| Classes | PascalCase | \`UserService\` |
+| Funções | snake_case | \`get_active_users\` |
+| Variáveis | snake_case | \`user_count\` |
+| Constantes | UPPER_SNAKE | \`MAX_RETRIES\` |
+| Arquivos | snake_case | \`user_service.py\` |
+| Módulos | snake_case | \`auth_module/\` |
+| Testes | snake_case + \_test | \`user_service_test.py\` |`;
+  }
+
+  if (lang === 'Dart') {
+    return `| Item | Padrão | Exemplo |
+|------|--------|---------|
+| Classes | PascalCase | \`UserService\` |
+| Funções | camelCase | \`getActiveUsers\` |
+| Variáveis | camelCase | \`userCount\` |
+| Constantes | camelCase (com const) | \`const maxRetries = 3\` |
+| Arquivos | snake_case | \`user_service.dart\` |
+| Widgets | PascalCase | \`UserProfileCard\` |
+| Testes | snake_case + \_test | \`user_service_test.dart\` |`;
+  }
+
+  if (lang === 'Go') {
+    return `| Item | Padrão | Exemplo |
+|------|--------|---------|
+| Types/Structs | PascalCase (exported) | \`UserService\` |
+| Functions (public) | PascalCase | \`GetActiveUsers\` |
+| Functions (private) | camelCase | \`parseInput\` |
+| Variables | camelCase | \`userCount\` |
+| Constants | PascalCase | \`MaxRetries\` |
+| Files | snake_case | \`user_service.go\` |
+| Tests | snake_case + \_test | \`user_service_test.go\` |`;
+  }
+
+  // Default: TypeScript/JavaScript
+  return `| Item | Padrão | Exemplo |
+|------|--------|---------|
+| Classes | PascalCase | \`UserService\` |
+| Interfaces | PascalCase (sem I prefix) | \`UserPayload\` |
+| Funções | camelCase | \`getActiveUsers\` |
+| Variáveis | camelCase | \`userCount\` |
+| Constantes | UPPER_SNAKE | \`MAX_RETRIES\` |
+| Enums | PascalCase | \`UserStatus\` |
+| Arquivos | kebab-case | \`user-service.ts\` |
+| Módulos (diretório) | kebab-case | \`user-management/\` |
+| Testes | kebab-case + .spec/.test | \`user-service.spec.ts\` |
+| Entities | PascalCase + .entity | \`User.entity.ts\` |
+| DTOs | PascalCase + .dto | \`CreateUserDto\` |
+| Controllers | PascalCase + .controller | \`user.controller.ts\` |
+| Services | PascalCase + .service | \`user.service.ts\` |`;
+}