@girardelli/architect 4.0.0 → 6.0.0

package/src/core/agent-generator/templates/helpers/summary-helpers.ts

@@ -0,0 +1,65 @@
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
+import { FrameworkInfo } from '../../types/stack.js';
+
+import { getEnriched, depthScale } from './base-helpers.js';
+
+export function domainBadge(ctx: TemplateContext): string {
+  const enriched = getEnriched(ctx);
+  if (!enriched.domain) return '';
+
+  const { domain } = enriched;
+  return `
+> 📌 **Domínio:** ${domain.domain} · **Sub-domínio:** ${domain.subDomain} · **Confiança:** ${Math.round(domain.confidence * 100)}%
+`;
+}
+
+export function complianceBadges(ctx: TemplateContext): string {
+  const enriched = getEnriched(ctx);
+  if (!enriched.domain?.compliance?.length) return '';
+
+  return `
+### ⚖️ Compliance Obrigatório
+
+${enriched.domain.compliance.map((c: any) => `- **${c.name}** — ${c.reason}
+  - Checks: ${c.mandatoryChecks.join(', ')}`).join('\n')}
+`;
+}
+
+export function depthIndicator(ctx: TemplateContext): string {
+  const enriched = getEnriched(ctx);
+  const depth = enriched.projectDepth || 'medium';
+  const labels: Record<string, string> = {
+    small: '🟢 Projeto Pequeno (< 50 arquivos)',
+    medium: '🟡 Projeto Médio (50-200 arquivos)',
+    large: '🟠 Projeto Grande (200-500 arquivos)',
+    enterprise: '🔴 Enterprise (500+ arquivos)',
+  };
+  return labels[depth];
+}
+
+export function modulesSummaryTable(ctx: TemplateContext): string {
+  const enriched = getEnriched(ctx);
+  if (!enriched.modules?.length) return '';
+
+  const maxModules = depthScale(ctx, { small: 5, medium: 10, large: 20, enterprise: 50 });
+  const modules = enriched.modules.slice(0, maxModules);
+
+  return `
+| Módulo | Arquivos | Linhas | Testes | Camada |
+|--------|----------|--------|--------|--------|
+${modules.map((m: any) => `| ${m.name} | ${m.fileCount} | ${m.lineCount > 0 ? m.lineCount.toLocaleString() : '—'} | ${m.hasTests ? '✅' : '❌'} | ${m.layer} |`).join('\n')}
+${enriched.modules.length > maxModules ? `\n> ... e mais ${enriched.modules.length - maxModules} módulos.` : ''}
+`;
+}
+
+export function integrationsSummary(ctx: TemplateContext): string {
+  const enriched = getEnriched(ctx);
+  if (!enriched.domain?.integrations?.length) return '';
+
+  return `
+### Integrações Externas Detectadas
+
+${enriched.domain.integrations.map((i: any) => `- **${i.name}** (${i.type}) — detectado em \`${i.detectedFrom}\``).join('\n')}
+`;
+}
+

package/src/{agent-generator → core/agent-generator}/templates/stack/index.ts

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Stack-specific rule generators.

package/src/core/agent-generator/templates/template-helpers.ts

@@ -0,0 +1,12 @@
+/**
+ * Template Helpers v3.2 — Facade para todos os utilitários agnósticos e estruturais.
+ *
+ * Refatorado na Fase 2.3.4: Erradicação final da God Class (777 → 20 linhas).
+ */
+
+export * from './helpers/base-helpers.js';
+export * from './helpers/cross-ref-helpers.js';
+export * from './helpers/summary-helpers.js';
+export * from './helpers/stack-helpers.js';
+export * from './helpers/structure-helpers.js';
+export * from './helpers/security-helpers.js';

package/src/core/agent-generator/types/agent.ts

@@ -0,0 +1,65 @@
+import { StackInfo } from './stack.js';
+
+export interface AgentAuditFinding {
+  type: 'MISSING' | 'OUTDATED' | 'IMPROVEMENT' | 'OK';
+  category: string;
+  file: string;
+  description: string;
+  suggestion?: string;
+}
+
+export type AgentItemStatus = 'KEEP' | 'MODIFY' | 'CREATE' | 'DELETE';
+
+export interface AgentItem {
+  name: string;
+  status: AgentItemStatus;
+  reason?: string;
+  description?: string;
+}
+
+export interface AgentSuggestion {
+  stack: StackInfo;
+  hasExistingAgents: boolean;
+  suggestedAgents: AgentItem[];
+  suggestedRules: AgentItem[];
+  suggestedGuards: AgentItem[];
+  suggestedWorkflows: AgentItem[];
+  suggestedSkills: { name: string; source: string; description: string; status: AgentItemStatus }[];
+  audit: AgentAuditFinding[];
+  command: string;
+}
+
+export interface AgentGeneratorConfig {
+  coverageMinimum: number;
+  scoreThreshold: number;
+  language: 'pt-BR' | 'en';
+  goldenRules: string[];
+  blockers: string[];
+}
+
+export const DEFAULT_AGENT_CONFIG: AgentGeneratorConfig = {
+  coverageMinimum: 80,
+  scoreThreshold: 70,
+  language: 'pt-BR',
+  goldenRules: [
+    'Git Flow completo (branch → PR → review → merge)',
+    'Arquitetura C4 (4 níveis de documentação)',
+    'BDD antes de código',
+    'TDD — Red → Green → Refactor',
+    'Diagnóstico obrigatório antes de codar',
+    'Mockup antes de qualquer UI',
+    'Nunca decidir sozinho — perguntar ao humano',
+    'Qualidade > Velocidade',
+    'Não abrir browser, não tirar screenshot — apenas código',
+  ],
+  blockers: [
+    'console.log / print() em código de produção',
+    'TODO / FIXME / HACK sem issue vinculada',
+    'any (TypeScript) / type: ignore (Python) sem justificativa',
+    'Testes com .skip() ou @pytest.mark.skip sem motivo',
+    'Secrets, tokens ou senhas hardcoded',
+    'Push direto em main/develop',
+    'Arquivos > 500 linhas sem justificativa',
+    'Imports circulares',
+  ],
+};

package/src/core/agent-generator/types/domain.ts

@@ -0,0 +1,63 @@
+/**
+ * Detailed module information extracted from project analysis.
+ */
+export interface ModuleDetail {
+  name: string;
+  path: string;
+  files: string[];
+  fileCount: number;
+  lineCount: number;
+  description: string;
+  hasTests: boolean;
+  testFiles: string[];
+  entities: string[];
+  controllers: string[];
+  services: string[];
+  layer: string;
+}
+
+/**
+ * API endpoint detected from route/controller files.
+ */
+export interface DetectedEndpoint {
+  method: string;
+  path: string;
+  file: string;
+  handler: string;
+  hasAuth: boolean;
+  hasValidation: boolean;
+}
+
+export interface BusinessEntity {
+  name: string;
+  source: string;
+  fields: string[];
+  relationships: string[];
+  layer: 'model' | 'entity' | 'schema' | 'dto' | 'unknown';
+}
+
+export interface ComplianceRequirement {
+  name: string;
+  reason: string;
+  mandatoryChecks: string[];
+}
+
+export interface ExternalIntegration {
+  name: string;
+  type: 'api' | 'database' | 'queue' | 'storage' | 'payment' | 'auth' | 'government' | 'other';
+  detectedFrom: string;
+}
+
+/**
+ * Domain classification inferred from project analysis.
+ */
+export interface DomainInsights {
+  domain: string;
+  subDomain: string;
+  description: string;
+  businessEntities: BusinessEntity[];
+  compliance: ComplianceRequirement[];
+  integrations: ExternalIntegration[];
+  keywords: string[];
+  confidence: number;
+}

package/src/core/agent-generator/types/stack.ts

@@ -0,0 +1,38 @@
+/**
+ * Stack detection result from project analysis.
+ */
+export interface StackInfo {
+  primary: string;
+  languages: string[];
+  frameworks: string[];
+  hasBackend: boolean;
+  hasFrontend: boolean;
+  hasMobile: boolean;
+  hasDatabase: boolean;
+  testFramework: string;
+  packageManager: string;
+}
+
+/**
+ * Detected framework with version, detected from dependency files.
+ */
+export interface FrameworkInfo {
+  name: string;
+  version: string | null;
+  category: 'web' | 'orm' | 'test' | 'lint' | 'build' | 'other';
+  confidence: number;
+}
+
+/**
+ * Detected toolchain — build, test, lint, run commands.
+ */
+export interface DetectedToolchain {
+  buildCmd: string;
+  testCmd: string;
+  lintCmd: string;
+  runCmd: string;
+  coverageCmd: string;
+  installCmd: string;
+  migrateCmd: string | null;
+  depsFile: string;
+}

package/src/core/agent-generator/types/template.ts

@@ -0,0 +1,31 @@
+import { AnalysisReport } from '../../types/core.js';
+import { RefactoringPlan } from '../../types/rules.js';
+import { StackInfo, FrameworkInfo, DetectedToolchain } from './stack.js';
+import { DomainInsights, ModuleDetail, DetectedEndpoint } from './domain.js';
+import { AgentGeneratorConfig } from './agent.js';
+
+export interface TemplateContext {
+  report: AnalysisReport;
+  plan: RefactoringPlan;
+  stack: StackInfo;
+  projectName: string;
+  stackLabel: string;
+  config: AgentGeneratorConfig;
+}
+
+export interface EnrichedTemplateContext extends TemplateContext {
+  domain: DomainInsights;
+  modules: ModuleDetail[];
+  endpoints: DetectedEndpoint[];
+  untestedModules: string[];
+  criticalPaths: string[]; // files with highest coupling
+  projectDepth: 'small' | 'medium' | 'large' | 'enterprise'; // drives template verbosity
+  /** Detected frameworks with versions */
+  detectedFrameworks: FrameworkInfo[];
+  /** Primary web framework (e.g., 'FastAPI', 'NestJS', 'Django') */
+  primaryFramework: FrameworkInfo | null;
+  /** Detected toolchain commands */
+  toolchain: DetectedToolchain;
+  /** Real project structure pattern detected */
+  projectStructure: 'clean-architecture' | 'mvc' | 'modular' | 'flat' | 'monorepo' | 'unknown';
+}

package/src/{analyzer.ts → core/analyzer.ts}

@@ -1,6 +1,7 @@
 import { readFileSync, existsSync } from 'fs';
 import { extname, relative, dirname, resolve, join } from 'path';
-import { DependencyEdge, Layer, FileNode } from './types.js';
+import { DependencyEdge, Layer } from './types/core.js';
+import { FileNode } from './types/infrastructure.js';
 
 export class ArchitectureAnalyzer {
   private projectPath: string;
@@ -277,8 +278,20 @@ export class ArchitectureAnalyzer {
       const path = node.path.toLowerCase();
       const name = node.name.toLowerCase();
 
-      // Data layer — check first (more specific patterns)
+      // Skip test files — they don't belong to any architectural layer
       if (
+        name.endsWith('.test.ts') || name.endsWith('.test.js') ||
+        name.endsWith('.spec.ts') || name.endsWith('.spec.js') ||
+        path.includes('/__tests__/') || path.includes('/__mocks__/')
+      ) {
+        // Don't categorize test files into any layer
+      }
+      // Skip node_modules files (safety barrier)
+      else if (path.includes('node_modules')) {
+        // Don't categorize third-party files
+      }
+      // Data layer — check first (more specific patterns)
+      else if (
         path.includes('/entities/') ||
         path.includes('/entity/') ||
         path.includes('/migrations/') ||

package/src/{analyzers → core/analyzers}/forecast.ts

@@ -17,7 +17,7 @@ import type {
   ModuleHistory,
   ChangeCoupling,
   FileHistory,
-} from './git-history.js';
+} from '../../infrastructure/git-history.js';
 import type { TemporalReport, TemporalScore } from './temporal-scorer.js';
 
 // ═══════════════════════════════════════════════════════════════

package/src/{analyzers → core/analyzers}/index.ts

@@ -2,7 +2,7 @@
  * Architect v4.0 Analyzers — Temporal & Predictive
  */
 
-export { GitHistoryAnalyzer } from './git-history.js';
+export { GitHistoryAnalyzer } from '../../infrastructure/git-history.js';
 export type {
   GitCommit,
   FileChange,
@@ -13,7 +13,7 @@ export type {
   GitHistoryReport,
   WeeklySnapshot,
   GitAnalyzerConfig,
-} from './git-history.js';
+} from '../../infrastructure/git-history.js';
 
 export { TemporalScorer } from './temporal-scorer.js';
 export type {

package/src/{analyzers → core/analyzers}/temporal-scorer.ts

@@ -14,7 +14,7 @@ import type {
   ModuleHistory,
   VelocityVector,
   GitHistoryReport,
-} from './git-history.js';
+} from '../../infrastructure/git-history.js';
 
 // ═══════════════════════════════════════════════════════════════
 // TYPES

package/src/{anti-patterns.ts → core/anti-patterns.ts}

@@ -1,15 +1,33 @@
 import { readFileSync } from 'fs';
-import { AntiPattern, FileNode, ArchitectConfig } from './types.js';
+import { AntiPattern, ArchitectConfig } from './types/core.js';
+import { FileNode } from './types/infrastructure.js';
 
 export class AntiPatternDetector {
   private config: ArchitectConfig;
   private dependencyGraph: Map<string, Set<string>>;
 
+  /** Paths that indicate third-party or build artifacts — never report anti-patterns here */
+  private static readonly EXCLUDED_PATH_SEGMENTS = [
+    'node_modules', '/dist/', '/build/', '/coverage/',
+    '/.next/', '/venv/', '/__pycache__/', '/target/',
+  ];
+
   constructor(config: ArchitectConfig) {
     this.config = config;
     this.dependencyGraph = new Map();
   }
 
+  /**
+   * Check if a file path belongs to the project's own source code.
+   * Returns false for node_modules, dist, build artifacts, etc.
+   */
+  private isProjectFile(filePath: string): boolean {
+    const normalized = filePath.replace(/\\/g, '/');
+    return !AntiPatternDetector.EXCLUDED_PATH_SEGMENTS.some(seg =>
+      normalized.includes(seg)
+    );
+  }
+
   detect(
     fileTree: FileNode,
     dependencies: Map<string, Set<string>>
@@ -42,7 +60,7 @@ export class AntiPatternDetector {
       this.config.antiPatterns?.godClass?.methodsThreshold || 10;
 
     this.walkFileTree(node, (file) => {
-      if (file.type === 'file' && (file.lines || 0) > threshold) {
+      if (file.type === 'file' && (file.lines || 0) > threshold && this.isProjectFile(file.path)) {
         const methods = this.countMethods(file.path);
         if (methods > methodThreshold) {
           patterns.push({
@@ -70,9 +88,12 @@ export class AntiPatternDetector {
     const recursionStack = new Set<string>();
 
     for (const file of this.dependencyGraph.keys()) {
+      // Only check cycles starting from project files
+      if (!this.isProjectFile(file)) continue;
+
       if (!visited.has(file)) {
         const cycle = this.findCycle(file, visited, recursionStack);
-        if (cycle) {
+        if (cycle && cycle.every(f => this.isProjectFile(f))) {
           patterns.push({
             name: 'Circular Dependency',
             severity: 'HIGH',
@@ -118,7 +139,7 @@ export class AntiPatternDetector {
     const patterns: AntiPattern[] = [];
 
     this.walkFileTree(node, (file) => {
-      if (file.type === 'file') {
+      if (file.type === 'file' && this.isProjectFile(file.path)) {
         const internalExports = this.countInternalExports(file.path);
         if (internalExports > 5) {
           patterns.push({
@@ -146,13 +167,13 @@ export class AntiPatternDetector {
     const patterns: AntiPattern[] = [];
 
     this.walkFileTree(node, (file) => {
-      if (file.type === 'file') {
+      if (file.type === 'file' && this.isProjectFile(file.path)) {
         const externalMethodCalls = (dependencies.get(file.path) || new Set())
           .size;
         const internalMethods = this.countMethods(file.path);
         const name = file.name.toLowerCase();
 
-        // Skip NestJS infrastructure files where external deps are by design
+        // Skip infrastructure files where external deps are by design
         const isInfraFile =
           name.endsWith('.module.ts') ||
           name.endsWith('.dto.ts') ||
@@ -163,7 +184,11 @@ export class AntiPatternDetector {
           name.endsWith('.filter.ts') ||
           name.endsWith('.decorator.ts') ||
           name.endsWith('.spec.ts') ||
-          name.endsWith('.test.ts');
+          name.endsWith('.test.ts') ||
+          name.endsWith('-engine.ts') ||
+          name.endsWith('-enricher.ts') ||
+          name.endsWith('-detector.ts') ||
+          file.path.includes('/scripts/');
 
         if (!isInfraFile && internalMethods > 0 && externalMethodCalls > internalMethods * 3) {
           patterns.push({
@@ -194,6 +219,14 @@ export class AntiPatternDetector {
         ?.changePropagationThreshold || 8;
 
     for (const [file, dependents] of dependencies) {
+      // Only report for project files
+      if (!this.isProjectFile(file)) continue;
+
+      const fileName = file.split('/').pop() || '';
+      const isBaseFile = ['index.ts', 'index.js', 'types.ts', 'logger.ts', 'config.ts', 'architect.ts'].includes(fileName);
+      const isExcludedDir = file.includes('tests/') || file.includes('scripts/') || file.includes('adapters/') || file.includes('agent-generator/');
+      if (isBaseFile || isExcludedDir) continue;
+
       if (dependents.size >= threshold) {
         patterns.push({
           name: 'Shotgun Surgery',
@@ -202,7 +235,7 @@ export class AntiPatternDetector {
           description: `Changes to this file likely require modifications in ${dependents.size} other files`,
           suggestion:
             'Refactor to reduce coupling and consolidate related functionality into modules',
-          affectedFiles: Array.from(dependents),
+          affectedFiles: Array.from(dependents).filter(f => this.isProjectFile(f)),
           metrics: {
             dependentFileCount: dependents.size,
           },