@girardelli/architect 4.0.0 → 6.0.0

package/src/core/agent-generator/engines/suggestion-engine.ts

@@ -0,0 +1,202 @@
+import { AnalysisReport, RefactoringPlan, StackInfo, AgentAuditFinding, AgentItem, AgentItemStatus, AgentSuggestion, StackDetector, ContextBuilder, AuditEngine, getStackRuleFileName } from './suggestion-engine_deps.js';
+
+import { existsSync, readdirSync, statSync } from "fs";
+import { join } from "path";
+
+
+
+
+
+
+
+
+
+export class SuggestionEngine {
+  private stackDetector = new StackDetector();
+  private contextBuilder = new ContextBuilder();
+  private auditEngine = new AuditEngine();
+
+  suggest(
+    report: AnalysisReport,
+    plan: RefactoringPlan,
+    projectPath: string,
+  ): AgentSuggestion {
+    const cleanReport = this.contextBuilder.sanitizeReport(report);
+    const stack = this.stackDetector.detect(cleanReport);
+    const agentDir = join(projectPath, '.agent');
+    const isExisting = existsSync(agentDir);
+
+    const existingFiles = (subdir: string): Set<string> => {
+      const dir = join(agentDir, subdir);
+      if (!existsSync(dir)) return new Set();
+      return new Set(readdirSync(dir).map(f => f.replace(/\.md$/, '')));
+    };
+
+    let audit: AgentAuditFinding[] = [];
+    if (isExisting) {
+      audit = this.auditEngine.auditExisting(agentDir, stack, report, plan);
+    }
+
+    const ctx = this.contextBuilder.buildContext(cleanReport, plan, stack, projectPath);
+
+    const existingAgents = existingFiles('agents');
+    const existingRules = existingFiles('rules');
+    const existingGuards = existingFiles('guards');
+    const existingWorkflows = existingFiles('workflows');
+    const existingSkillsDir = join(agentDir, 'skills');
+    const existingSkillNames = existsSync(existingSkillsDir)
+      ? new Set(readdirSync(existingSkillsDir).filter(f => {
+          try { return statSync(join(existingSkillsDir, f)).isDirectory(); } catch { return false; }
+        }))
+      : new Set<string>();
+
+    const itemStatus = (name: string, existing: Set<string>): AgentItemStatus => {
+      const found = [...existing].some(e => e.toLowerCase() === name.toLowerCase());
+      if (!found) return 'CREATE';
+      const hasImprovement = audit.some(
+        f => f.file.toLowerCase().includes(name.toLowerCase()) && (f.type === 'IMPROVEMENT' || f.type === 'OUTDATED')
+      );
+      return hasImprovement ? 'MODIFY' : 'KEEP';
+    };
+
+    // ── Agent definitions ──
+    const agentDefs: { name: string; desc: string }[] = [
+      { name: 'AGENT-ORCHESTRATOR', desc: 'Centro de comando — decompõe requisições, enforça gates, coordena agentes' },
+    ];
+    if (stack.hasBackend) agentDefs.push({
+      name: `${stack.primary.toUpperCase()}-BACKEND-DEVELOPER`,
+      desc: `Especialista em ${stack.primary} — APIs, serviços, lógica de negócio, integration docs`,
+    });
+    if (stack.hasFrontend) {
+      const FRONTEND_FWS = ['Angular', 'Vue', 'Vue.js', 'Next.js', 'React', 'Nuxt', 'Svelte', 'Remix'];
+      const detectedFw = ctx.detectedFrameworks?.find(f => FRONTEND_FWS.includes(f.name));
+      const fw = detectedFw?.name ||
+        stack.frameworks.find(f => FRONTEND_FWS.includes(f)) || 'FRONTEND';
+      agentDefs.push({
+        name: `${fw.toUpperCase().replace('.', '').replace(/\s/g, '-')}-FRONTEND-DEVELOPER`,
+        desc: `Componentes ${fw}, state management, UX responsiva, todos os estados UI`,
+      });
+    }
+    if (stack.hasMobile) agentDefs.push({
+      name: 'FLUTTER-UI-DEVELOPER',
+      desc: 'Screens mobile, widgets, navegação, integração API, padrão visual do app',
+    });
+    if (stack.hasDatabase) agentDefs.push({
+      name: 'DATABASE-ENGINEER',
+      desc: 'Schema design, migrations reversíveis, indexação, performance de queries',
+    });
+    agentDefs.push(
+      { name: 'SECURITY-AUDITOR', desc: 'OWASP Top 10, STRIDE threat model, compliance, vulnerabilidades' },
+      { name: 'QA-TEST-ENGINEER', desc: 'BDD/TDD, cobertura mínima, planos de teste, regressão' },
+      { name: 'TECH-DEBT-CONTROLLER', desc: 'Score tracking, anti-patterns, refatorações, metas de qualidade' },
+    );
+
+    const ruleDefs: { name: string; desc: string }[] = [
+      { name: '00-general', desc: '9 Regras de Ouro, Git Flow, naming conventions, ações proibidas' },
+      { name: '01-architecture', desc: 'Separação de camadas, dependency rules, padrões de módulo' },
+      { name: '02-security', desc: 'Sanitização, secrets management, validação, OWASP' },
+    ];
+    const stackRuleName = getStackRuleFileName(ctx);
+    if (stackRuleName) {
+      const fwLabel = stack.frameworks[0] || stack.primary;
+      ruleDefs.push({ name: stackRuleName, desc: `Regras específicas ${fwLabel} — patterns, anti-patterns, checklist` });
+    }
+
+    const guardDefs = [
+      { name: 'PREFLIGHT', desc: '6-phase checklist pré-ação: ambiente → leitura → negócio → camada → commit → done' },
+      { name: 'QUALITY-GATES', desc: '3 níveis (CRITICAL/IMPORTANT/DESIRABLE), métricas, blockers, verificação em 4 estágios' },
+      { name: 'CODE-REVIEW-CHECKLIST', desc: 'Review em 6 dimensões: funcional, qualidade, testes, segurança, performance, arquitetura' },
+    ];
+
+    const workflowDefs = [
+      { name: 'new-feature', desc: '10 steps com 6 approval gates, mockup-first, backend-first, integration doc' },
+      { name: 'fix-bug', desc: '10 steps: diagnóstico → root cause → RED test → fix mínimo → regressão → docs' },
+      { name: 'review', desc: 'Code review em 6 dimensões com checklist estruturado' },
+    ];
+
+    // Build items
+    const suggestedAgents: AgentItem[] = agentDefs.map(({ name, desc }) => ({
+      name, status: itemStatus(name, existingAgents), description: desc,
+    }));
+    for (const existing of existingAgents) {
+      if (!agentDefs.some(d => d.name.toLowerCase() === existing.toLowerCase())) {
+        suggestedAgents.push({ name: existing, status: 'KEEP', reason: 'Custom agent', description: 'Agente customizado do projeto' });
+      }
+    }
+
+    const suggestedRules: AgentItem[] = ruleDefs.map(({ name, desc }) => ({
+      name, status: itemStatus(name, existingRules), description: desc,
+    }));
+    for (const existing of existingRules) {
+      if (!ruleDefs.some(d => d.name.toLowerCase() === existing.toLowerCase())) {
+        suggestedRules.push({ name: existing, status: 'KEEP', reason: 'Custom rule' });
+      }
+    }
+
+    const suggestedGuards: AgentItem[] = guardDefs.map(({ name, desc }) => ({
+      name, status: itemStatus(name, existingGuards), description: desc,
+    }));
+
+    const suggestedWorkflows: AgentItem[] = workflowDefs.map(({ name, desc }) => ({
+      name, status: itemStatus(name, existingWorkflows), description: desc,
+    }));
+    for (const existing of existingWorkflows) {
+      if (!workflowDefs.some(d => d.name.toLowerCase() === existing.toLowerCase())) {
+        suggestedWorkflows.push({ name: existing, status: 'KEEP', reason: 'Custom workflow' });
+      }
+    }
+
+    // Skills
+    const skillEntries = this.buildSkillEntries(stack, existingSkillNames);
+
+    return {
+      stack,
+      hasExistingAgents: isExisting,
+      suggestedAgents,
+      suggestedRules,
+      suggestedGuards,
+      suggestedWorkflows,
+      suggestedSkills: skillEntries,
+      audit,
+      command: `architect agents ${projectPath}`,
+    };
+  }
+
+  public buildSkillEntries(stack: StackInfo, existing: Set<string>) {
+    const entries: { name: string; source: string; description: string; status: AgentItemStatus }[] = [
+      { name: 'test-driven-development', source: 'anthropic/courses/test-driven-development', description: 'TDD: Red → Green → Refactor', status: 'CREATE' },
+      { name: 'systematic-debugging', source: 'anthropic/courses/systematic-debugging', description: 'Structured debugging methodology', status: 'CREATE' },
+      { name: 'code-review', source: 'anthropic/courses/requesting-code-review', description: 'Code review best practices', status: 'CREATE' },
+      { name: 'security-best-practices', source: 'anthropic/courses/security-best-practices', description: 'Security patterns and vulnerability prevention', status: 'CREATE' },
+      { name: 'performance-optimization', source: 'anthropic/courses/performance-optimization', description: 'Performance analysis and optimization', status: 'CREATE' },
+      { name: 'git-workflow', source: 'anthropic/courses/git-workflow', description: 'Git branching, commits, collaboration', status: 'CREATE' },
+    ];
+
+    // Stack-specific skills
+    if (stack.languages.includes('TypeScript') || stack.languages.includes('JavaScript')) {
+      entries.push({ name: 'api-design-principles', source: 'anthropic/courses/api-design-principles', description: 'REST/GraphQL API design', status: 'CREATE' });
+    }
+    if (stack.frameworks.includes('Angular') || stack.frameworks.includes('Vue') || stack.frameworks.includes('React') || stack.frameworks.includes('Next.js')) {
+      entries.push(
+        { name: 'frontend-design', source: 'anthropic/courses/frontend-design', description: 'Modern frontend patterns', status: 'CREATE' },
+        { name: 'web-accessibility', source: 'anthropic/courses/web-accessibility', description: 'WCAG accessibility standards', status: 'CREATE' },
+      );
+    }
+    if (stack.languages.includes('Dart') || stack.frameworks.includes('Flutter')) {
+      entries.push({ name: 'flutter-animations', source: 'anthropic/courses/flutter-animations', description: 'Flutter animation patterns', status: 'CREATE' });
+    }
+    if (stack.languages.includes('Python')) {
+      entries.push({ name: 'python-performance', source: 'anthropic/courses/python-performance-optimization', description: 'Python optimization and profiling', status: 'CREATE' });
+    }
+    if (stack.hasDatabase) {
+      entries.push({ name: 'database-schema-design', source: 'anthropic/courses/database-schema-design', description: 'Schema design, indexing, migrations', status: 'CREATE' });
+    }
+
+    // Update status based on existing
+    for (const entry of entries) {
+      if (existing.has(entry.name)) entry.status = 'KEEP';
+    }
+
+    return entries;
+  }
+}

package/src/core/agent-generator/engines/suggestion-engine_deps.ts

@@ -0,0 +1,8 @@
+export { AnalysisReport } from '../../types/core.js';
+export { RefactoringPlan } from '../../types/rules.js';
+export { StackInfo } from '../types/stack.js';
+export { AgentAuditFinding, AgentItem, AgentItemStatus, AgentSuggestion } from '../types/agent.js';
+export { StackDetector } from '../stack-detector.js';
+export { ContextBuilder } from './context-builder.js';
+export { AuditEngine } from './audit-engine.js';
+export { getStackRuleFileName } from '../templates/stack/index.js';

package/src/core/agent-generator/enrichers/analysis-helpers.ts

@@ -0,0 +1,58 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { AnalysisReport } from '../../types/core.js';
+import { ModuleDetail, DetectedEndpoint } from '../types/domain.js';
+import { EnrichedTemplateContext } from '../types/template.js';
+
+export class AnalysisHelpers {
+public findUntestedModules(modules: ModuleDetail[]): string[] {
+    return modules
+      .filter(m => !m.hasTests && m.fileCount > 1)
+      .map(m => m.name);
+  }
+
+
+public findCriticalPaths(report: AnalysisReport): string[] {
+    const coupling = new Map<string, number>();
+    for (const edge of report.dependencyGraph.edges) {
+      coupling.set(edge.from, (coupling.get(edge.from) || 0) + edge.weight);
+      coupling.set(edge.to, (coupling.get(edge.to) || 0) + edge.weight);
+    }
+    return [...coupling.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 10)
+      .map(([file]) => file);
+  }
+
+
+public classifyProjectDepth(report: AnalysisReport): EnrichedTemplateContext['projectDepth'] {
+    const files = report.projectInfo.totalFiles;
+    const lines = report.projectInfo.totalLines;
+    if (files > 500 || lines > 100000) return 'enterprise';
+    if (files > 200 || lines > 50000) return 'large';
+    if (files > 50 || lines > 10000) return 'medium';
+    return 'small';
+  }
+
+
+public countFileLines(projectPath: string, filePath: string): number {
+    try {
+      const fullPath = join(projectPath, filePath);
+      if (!existsSync(fullPath)) return 0;
+
+      const stats = statSync(fullPath);
+      // Skip files larger than 1MB — estimate based on average line length
+      if (stats.size > 1_000_000) {
+        return Math.round(stats.size / 45); // ~45 chars avg per line
+      }
+      if (stats.size === 0) return 0;
+
+      const content = readFileSync(fullPath, 'utf-8');
+      return content.split('\n').length;
+    } catch {
+      return 0;
+    }
+  }
+
+
+}

package/src/core/agent-generator/enrichers/description-generator.ts

@@ -0,0 +1,91 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { AnalysisReport } from '../../types/core.js';
+import { ModuleDetail, DetectedEndpoint } from '../types/domain.js';
+import { EnrichedTemplateContext } from '../types/template.js';
+
+export class DescriptionGenerator {
+public generateSmartDescription(mod: ModuleDetail): string {
+    const name = mod.name.toLowerCase();
+    const parts: string[] = [];
+
+    // Pattern-based descriptions
+    const descriptionPatterns: Record<string, string> = {
+      'extractors': 'Extração e parsing de dados de documentos',
+      'ocr': 'Reconhecimento óptico de caracteres (OCR)',
+      'guards': 'Validação e proteção de fluxos de dados',
+      'confidence': 'Cálculo de confiança e scoring de dados extraídos',
+      'routes': 'Definição de rotas e endpoints da API',
+      'workers': 'Processamento assíncrono e workers de background',
+      'persistence': 'Camada de persistência e acesso a dados',
+      'storage': 'Gerenciamento de armazenamento de arquivos',
+      'agents': 'Agentes de processamento e automação',
+      'auth': 'Autenticação e gerenciamento de sessão',
+      'users': 'Gerenciamento de usuários e perfis',
+      'notifications': 'Sistema de notificações e alertas',
+      'payments': 'Processamento de pagamentos e transações',
+      'reports': 'Geração de relatórios e dashboards',
+      'search': 'Motor de busca e indexação',
+      'cache': 'Camada de cache e otimização de performance',
+      'queue': 'Filas de mensagens e processamento assíncrono',
+      'email': 'Envio e gerenciamento de e-mails',
+      'upload': 'Upload e processamento de arquivos',
+      'migration': 'Migrações de banco de dados',
+      'seed': 'Dados iniciais e seed do banco',
+      'fixtures': 'Fixtures e dados de teste',
+      'middleware': 'Middleware de requisição/resposta',
+      'dependencies': 'Injeção de dependências e configuração',
+      'exceptions': 'Tratamento de erros e exceções customizadas',
+      'enums': 'Enumerações e constantes de domínio',
+      'events': 'Sistema de eventos e event handlers',
+      'value_objects': 'Value Objects do domínio (imutáveis)',
+      'entities': 'Entidades de domínio com identidade',
+      'services': 'Serviços de domínio e lógica de negócio',
+      'interfaces': 'Contratos e interfaces de abstração',
+      'repositories': 'Repositórios de acesso a dados',
+      'mappers': 'Mapeamento entre camadas (DTO ↔ Entity)',
+      'validators': 'Validação de dados e regras de negócio',
+      'serializers': 'Serialização/deserialização de dados',
+      'schemas': 'Schemas de validação e contratos',
+    };
+
+    // Try exact match first
+    for (const [pattern, desc] of Object.entries(descriptionPatterns)) {
+      if (name === pattern || name.endsWith(`/${pattern}`)) {
+        parts.push(desc);
+        break;
+      }
+    }
+
+    // Try partial match
+    if (parts.length === 0) {
+      for (const [pattern, desc] of Object.entries(descriptionPatterns)) {
+        if (name.includes(pattern)) {
+          parts.push(desc);
+          break;
+        }
+      }
+    }
+
+    // Add composition info
+    const composition: string[] = [];
+    if (mod.controllers.length > 0) composition.push(`${mod.controllers.length} endpoint(s)`);
+    if (mod.services.length > 0) composition.push(`${mod.services.length} service(s)`);
+    if (mod.entities.length > 0) composition.push(`entities: ${mod.entities.join(', ')}`);
+
+    if (composition.length > 0) {
+      parts.push(composition.join(' · '));
+    }
+
+    // Fallback: file count + line count
+    if (parts.length === 0) {
+      parts.push(`${mod.fileCount} arquivo(s)`);
+    }
+    if (mod.lineCount > 0) {
+      parts.push(`${mod.lineCount.toLocaleString()} linhas`);
+    }
+
+    return parts.join(' — ');
+  }
+
+}

package/src/core/agent-generator/enrichers/endpoint-extractor.ts

@@ -0,0 +1,114 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { AnalysisReport } from '../../types/core.js';
+import { ModuleDetail, DetectedEndpoint } from '../types/domain.js';
+import { EnrichedTemplateContext } from '../types/template.js';
+
+import { LayerClassifier } from './layer-classifier.js';
+
+export class EndpointExtractor {
+  private layerClassifier = new LayerClassifier();
+
+public extractEndpoints(report: AnalysisReport, modules: ModuleDetail[]): DetectedEndpoint[] {
+    const endpoints: DetectedEndpoint[] = [];
+    const nodes = report.dependencyGraph.nodes;
+
+    for (const filePath of nodes) {
+      const lower = filePath.toLowerCase();
+      if (!this.layerClassifier.isControllerOrRouteFile(lower)) continue;
+
+      const resourceName = this.extractResourceFromFile(filePath);
+      if (!resourceName || resourceName === 'init' || resourceName === 'index') continue;
+
+      const isAuthRoute = lower.includes('auth');
+      const isHealthRoute = lower.includes('health') || lower.includes('status');
+      const isSearchRoute = lower.includes('search') || lower.includes('query');
+      const isMetricsRoute = lower.includes('metric') || lower.includes('monitor');
+
+      if (isHealthRoute) {
+        endpoints.push({
+          method: 'GET', path: `/health`, file: filePath,
+          handler: 'health_check', hasAuth: false, hasValidation: false,
+        });
+        continue;
+      }
+
+      if (isMetricsRoute) {
+        endpoints.push({
+          method: 'GET', path: `/metrics`, file: filePath,
+          handler: 'get_metrics', hasAuth: this.layerClassifier.fileReferencesAuth(filePath, report), hasValidation: false,
+        });
+        continue;
+      }
+
+      if (isAuthRoute) {
+        endpoints.push(
+          { method: 'POST', path: `/auth/login`, file: filePath, handler: 'login', hasAuth: false, hasValidation: true },
+          { method: 'POST', path: `/auth/register`, file: filePath, handler: 'register', hasAuth: false, hasValidation: true },
+          { method: 'POST', path: `/auth/refresh`, file: filePath, handler: 'refresh_token', hasAuth: true, hasValidation: false },
+        );
+        continue;
+      }
+
+      if (isSearchRoute) {
+        endpoints.push({
+          method: 'GET', path: `/${resourceName}/search`, file: filePath,
+          handler: `search_${resourceName}`, hasAuth: this.layerClassifier.fileReferencesAuth(filePath, report), hasValidation: true,
+        });
+        endpoints.push({
+          method: 'POST', path: `/${resourceName}/search`, file: filePath,
+          handler: `advanced_search_${resourceName}`, hasAuth: this.layerClassifier.fileReferencesAuth(filePath, report), hasValidation: true,
+        });
+        continue;
+      }
+
+      // Standard CRUD
+      const hasAuth = this.layerClassifier.fileReferencesAuth(filePath, report);
+      const hasValidation = this.layerClassifier.fileReferencesValidation(filePath, report);
+      const crud = [
+        { method: 'GET', path: `/${resourceName}`, handler: `list_${resourceName}` },
+        { method: 'GET', path: `/${resourceName}/{id}`, handler: `get_${resourceName}` },
+        { method: 'POST', path: `/${resourceName}`, handler: `create_${resourceName}` },
+        { method: 'PUT', path: `/${resourceName}/{id}`, handler: `update_${resourceName}` },
+        { method: 'DELETE', path: `/${resourceName}/{id}`, handler: `delete_${resourceName}` },
+      ];
+      for (const c of crud) {
+        endpoints.push({ method: c.method, path: c.path, file: filePath, handler: c.handler, hasAuth, hasValidation });
+      }
+    }
+
+    // Deduplicate endpoints — same method+path from .ts and .js variants
+    const seen = new Set<string>();
+    const deduped = endpoints.filter(ep => {
+      const key = `${ep.method}:${ep.path}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+    return deduped;
+  }
+
+
+public extractResourceFromFile(filePath: string): string {
+    const parts = filePath.split('/');
+    const fileName = parts[parts.length - 1]
+      .replace(/\.[^.]+$/, '')
+      .replace(/(Controller|Router|Route|View|Handler|Endpoint|Resource|Blueprint)$/i, '')
+      .replace(/[-_]/g, '')
+      .toLowerCase();
+
+    if (fileName && fileName !== '__init__' && fileName !== 'index' && fileName !== 'base' && fileName.length > 1) {
+      return fileName;
+    }
+
+    const parent = parts[parts.length - 2];
+    if (parent && parent.toLowerCase() !== 'routes' && parent.toLowerCase() !== 'controllers') {
+      return parent.toLowerCase().replace(/[-_]/g, '');
+    }
+
+    return '';
+  }
+
+
+}

package/src/core/agent-generator/enrichers/layer-classifier.ts

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { AnalysisReport } from '../../types/core.js';
+import { ModuleDetail, DetectedEndpoint } from '../types/domain.js';
+import { EnrichedTemplateContext } from '../types/template.js';
+
+export class LayerClassifier {
+public isTestFile(lower: string): boolean {
+    return lower.includes('/test') || lower.includes('/spec') || lower.includes('__tests__')
+      || lower.includes('.test.') || lower.includes('.spec.')
+      || lower.includes('_test.py') || lower.includes('_test.go')
+      || lower.includes('test_') && lower.endsWith('.py')
+      || lower.includes('/tests/');
+  }
+
+
+public isEntityFile(lower: string): boolean {
+    return lower.includes('/model') || lower.includes('/entity') || lower.includes('/entities')
+      || lower.includes('/schema') || lower.includes('/value_object')
+      || lower.includes('.model.') || lower.includes('.entity.')
+      || lower.endsWith('models.py')
+      || lower.includes('/domain/') && (lower.endsWith('.java') || lower.endsWith('.kt')) && !lower.includes('service') && !lower.includes('repository')
+      || lower.includes('/models/') && lower.endsWith('.php');
+  }
+
+
+public isControllerOrRouteFile(lower: string): boolean {
+    if (lower.includes('.controller.')) return true;
+    if (lower.includes('.router.')) return true;
+    if (lower.includes('/routes/') && !lower.includes('__init__')) return true;
+    if (lower.includes('/route/') && !lower.includes('__init__')) return true;
+    if (lower.endsWith('views.py') || lower.endsWith('_view.py')) return true;
+    if (lower.endsWith('urls.py')) return true;
+    if (lower.includes('blueprint')) return true;
+    if ((lower.endsWith('.java') || lower.endsWith('.kt')) && lower.includes('controller')) return true;
+    if (lower.includes('/controllers/') && lower.endsWith('.php')) return true;
+    if (lower.endsWith('.go') && (lower.includes('handler') || lower.includes('router'))) return true;
+    if (lower.includes('/controllers/') && lower.endsWith('.rb')) return true;
+    if (lower.includes('/endpoint') || lower.includes('/handler')) return true;
+    return false;
+  }
+
+
+public isServiceFile(lower: string): boolean {
+    return lower.includes('service') || lower.includes('usecase') || lower.includes('use_case')
+      || lower.includes('use-case') || lower.includes('interactor')
+      || lower.includes('/application/') && !lower.includes('interface') && !lower.includes('__init__');
+  }
+
+
+public isGenericDir(name: string): boolean {
+    const generic = new Set([
+      'src', 'lib', 'app', 'main', 'common', 'shared', 'utils', 'helpers',
+      'config', 'configuration', 'middleware', 'middlewares', 'guards', 'pipes',
+      'interceptors', 'filters', 'decorators',
+      'tests', 'test', '__tests__', 'spec', 'specs', 'e2e', 'migrations', 'seeds',
+      'dto', 'dtos', 'entities', 'models', 'schemas', 'interfaces', 'types', 'typings',
+      'controllers', 'services', 'repositories', 'providers', 'factories',
+      'data', 'domain', 'presentation', 'infrastructure', 'application',
+      'core', 'base', 'abstract', 'generics', 'constants', 'enums',
+      'public', 'static', 'assets', 'resources', 'templates', 'views',
+      'internal', 'pkg', 'cmd', 'vendor', 'node_modules',
+      'adapters', 'ports', 'usecases', 'use_cases', 'value_objects',
+      'events', 'exceptions', 'errors', 'signals', 'hooks',
+    ]);
+    return generic.has(name);
+  }
+
+
+public inferFileLayer(filePath: string): string {
+    const lower = filePath.toLowerCase();
+
+    // Monorepo package-level classification
+    const packagesMatch = lower.match(/packages\/([^/]+)/);
+    if (packagesMatch) {
+      const pkgName = packagesMatch[1];
+      // Classify by package name semantics
+      if (['dashboard', 'web', 'frontend', 'app', 'ui'].includes(pkgName)) return 'UI';
+      if (['api', 'cloud', 'server', 'backend'].includes(pkgName)) return 'API';
+      if (['core', 'bridge', 'engine'].includes(pkgName)) return 'Service';
+      if (['cli', 'command'].includes(pkgName)) return 'CLI';
+      if (['types', 'events', 'mcp', 'autonomy'].includes(pkgName)) return 'Infrastructure';
+      return 'Package';
+    }
+
+    if (lower.includes('/route') || lower.includes('/controller') || lower.includes('/endpoint')
+      || lower.includes('/api/') || lower.includes('/presentation/') || lower.includes('/handler')
+      || (lower.includes('/view') && !lower.includes('/review'))
+      || lower.includes('/urls') || lower.includes('/blueprint')
+      || lower.includes('/http/')) return 'API';
+
+    if (lower.includes('/service') || lower.includes('/usecase') || lower.includes('/use_case')
+      || lower.includes('/use-case') || lower.includes('/application/')) return 'Service';
+
+    if (lower.includes('/model') || lower.includes('/entity') || lower.includes('/entities')
+      || lower.includes('/schema') || lower.includes('/repository') || lower.includes('/persistence')
+      || lower.includes('/migration') || lower.includes('/domain/')
+      || lower.includes('/value_object') || lower.includes('/serializer')) return 'Data';
+
+    if (lower.includes('/component') || lower.includes('/page') || lower.includes('/screen')
+      || lower.includes('/widget') || lower.includes('/template')
+      || lower.includes('/partial') || lower.includes('/layout')) return 'UI';
+
+    if (lower.includes('/config') || lower.includes('/middleware') || lower.includes('/infra')
+      || lower.includes('/infrastructure/') || lower.includes('/storage')
+      || lower.includes('/extraction') || lower.includes('/adapter')
+      || lower.includes('/worker') || lower.includes('/consumer')
+      || lower.includes('/queue') || lower.includes('/cache')
+      || lower.includes('/email') || lower.includes('/notification')) return 'Infrastructure';
+
+    if (lower.includes('/cli/') || lower.includes('/command') || lower.includes('/script')
+      || lower.includes('/management/commands')) return 'CLI';
+
+    return 'Other';
+  }
+
+
+public extractEntityName(filePath: string): string | null {
+    const parts = filePath.split('/');
+    const fileName = parts[parts.length - 1];
+    const name = fileName
+      .replace(/\.[^.]+$/, '')
+      .replace(/\.(model|entity|schema|dto)$/i, '')
+      .replace(/(Model|Entity|Schema|Dto)$/i, '')
+      .replace(/[-_]/g, ' ')
+      .replace(/\b\w/g, l => l.toUpperCase())
+      .trim();
+
+    const skip = new Set(['Index', 'Base', 'Init', '__Init__', 'Abstract', 'Models', 'Entities', 'Schemas']);
+    if (name && !skip.has(name)) {
+      return name;
+    }
+    return null;
+  }
+
+
+public fileReferencesAuth(filePath: string, report: AnalysisReport): boolean {
+    const edges = report.dependencyGraph.edges.filter(e => e.from === filePath);
+    return edges.some(e => {
+      const to = e.to.toLowerCase();
+      return to.includes('auth') || to.includes('guard') || to.includes('permission')
+        || to.includes('jwt') || to.includes('token') || to.includes('security')
+        || to.includes('dependencies/auth') || to.includes('middleware/auth');
+    });
+  }
+
+  public fileReferencesValidation(filePath: string, report: AnalysisReport): boolean {
+    const edges = report.dependencyGraph.edges.filter(e => e.from === filePath);
+    return edges.some(e => {
+      const to = e.to.toLowerCase();
+      return to.includes('dto') || to.includes('schema') || to.includes('validator')
+        || to.includes('pipe') || to.includes('serializer') || to.includes('form')
+        || to.includes('pydantic') || to.includes('marshmallow');
+    });
+  }
+}