@girardelli/architect 4.0.0 → 6.0.0

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

@@ -0,0 +1,203 @@
+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';
+import { DescriptionGenerator } from './description-generator.js';
+import { AnalysisHelpers } from './analysis-helpers.js';
+
+export class ModuleExtractor {
+  private layerClassifier = new LayerClassifier();
+  private descriptionGenerator = new DescriptionGenerator();
+  private analysisHelpers = new AnalysisHelpers();
+
+public extractModules(report: AnalysisReport, projectPath: string): ModuleDetail[] {
+    const modules = new Map<string, ModuleDetail>();
+    const nodes = report.dependencyGraph.nodes;
+
+    for (const filePath of nodes) {
+      const moduleName = this.inferModuleName(filePath);
+      if (!moduleName) continue;
+
+      if (!modules.has(moduleName)) {
+        modules.set(moduleName, {
+          name: moduleName,
+          path: this.inferModulePath(filePath, moduleName),
+          files: [],
+          fileCount: 0,
+          lineCount: 0,
+          description: '',
+          hasTests: false,
+          testFiles: [],
+          entities: [],
+          controllers: [],
+          services: [],
+          layer: this.layerClassifier.inferFileLayer(filePath),
+        });
+      }
+
+      const mod = modules.get(moduleName)!;
+      mod.files.push(filePath);
+      mod.fileCount++;
+
+      // v3.1: Count real lines
+      mod.lineCount += this.analysisHelpers.countFileLines(projectPath, filePath);
+
+      const lower = filePath.toLowerCase();
+      if (this.layerClassifier.isTestFile(lower)) {
+        mod.hasTests = true;
+        mod.testFiles.push(filePath);
+      }
+      if (this.layerClassifier.isEntityFile(lower)) {
+        const entityName = this.layerClassifier.extractEntityName(filePath);
+        if (entityName) mod.entities.push(entityName);
+      }
+      if (this.layerClassifier.isControllerOrRouteFile(lower)) {
+        mod.controllers.push(filePath);
+      }
+      if (this.layerClassifier.isServiceFile(lower)) {
+        mod.services.push(filePath);
+      }
+    }
+
+    // Enrich with descriptions from project summary
+    if (report.projectSummary?.modules) {
+      for (const summaryMod of report.projectSummary.modules) {
+        const key = summaryMod.name.toLowerCase();
+        for (const [modName, mod] of modules) {
+          if (modName.toLowerCase().includes(key) || key.includes(modName.toLowerCase())) {
+            mod.description = summaryMod.description;
+            break;
+          }
+        }
+      }
+    }
+
+    // v3.1: Smart descriptions for modules without one
+    for (const mod of modules.values()) {
+      if (!mod.description) {
+        mod.description = this.descriptionGenerator.generateSmartDescription(mod);
+      }
+    }
+
+    return [...modules.values()].sort((a, b) => b.fileCount - a.fileCount);
+  }
+
+
+public inferModuleName(filePath: string): string | null {
+    const parts = filePath.split('/');
+    const lower = filePath.toLowerCase();
+
+    // Skip __init__.py / index files as standalone modules
+    const fileName = parts[parts.length - 1].toLowerCase();
+    if (fileName === '__init__.py' || fileName === 'index.ts' || fileName === 'index.js' || fileName === 'index.py') {
+      // Only process if it's in a meaningful directory
+    }
+
+    // ── Strategy 1: Explicit module markers ──
+    const moduleMarkers = ['modules', 'features', 'apps', 'domains', 'packages', 'components', 'pages', 'bundles'];
+    for (let i = 0; i < parts.length; i++) {
+      if (moduleMarkers.includes(parts[i].toLowerCase()) && parts[i + 1]) {
+        return parts[i + 1];
+      }
+    }
+
+    // ── Strategy 2: Clean Architecture / DDD layers ──
+    const cleanArchLayers = new Set([
+      'domain', 'application', 'infrastructure', 'presentation',
+      'core', 'adapters', 'ports', 'usecases', 'use_cases',
+    ]);
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (cleanArchLayers.has(parts[i].toLowerCase()) && parts[i + 1]) {
+        const nextDir = parts[i + 1].toLowerCase();
+        const subLayers = new Set([
+          'services', 'entities', 'models', 'repositories', 'interfaces',
+          'value_objects', 'events', 'exceptions', 'enums', 'dto', 'dtos',
+          'controllers', 'views', 'routes', 'api', 'workers', 'consumers',
+          'persistence', 'storage', 'extraction', 'agents', 'adapters',
+          'mappers', 'factories', 'providers', 'guards', 'middleware',
+          'dependencies', 'schemas', 'serializers', 'signals', 'tasks',
+          'commands', 'queries', 'handlers', 'listeners',
+        ]);
+
+        if (subLayers.has(nextDir)) {
+          if (parts[i + 2] && !parts[i + 2].includes('.')) {
+            return parts[i + 2]; // e.g., infrastructure/extraction/extractors → extractors
+          }
+          return `${parts[i]}/${parts[i + 1]}`;
+        }
+
+        if (!this.layerClassifier.isGenericDir(nextDir) && nextDir.length > 2 && !nextDir.startsWith('__')) {
+          return parts[i + 1];
+        }
+      }
+    }
+
+    // ── Strategy 3: Django apps pattern ──
+    const djangoMarkers = ['views.py', 'models.py', 'urls.py', 'serializers.py', 'admin.py', 'apps.py', 'forms.py'];
+    if (djangoMarkers.some(m => lower.endsWith(m))) {
+      const parentDir = parts[parts.length - 2];
+      if (parentDir && !this.layerClassifier.isGenericDir(parentDir.toLowerCase())) {
+        return parentDir;
+      }
+    }
+
+    // ── Strategy 4: Java/PHP package-based ──
+    const javaPackageMarkers = ['com', 'org', 'net', 'io', 'br'];
+    for (let i = 0; i < parts.length; i++) {
+      if (javaPackageMarkers.includes(parts[i].toLowerCase()) && parts[i + 2]) {
+        return parts[i + 2];
+      }
+    }
+
+    // PHP namespace: App/Http/Controllers/UserController.php → user
+    if (lower.includes('/http/controllers/') || lower.includes('/http/requests/')) {
+      const parentDir = parts[parts.length - 2];
+      if (parentDir && parentDir.toLowerCase() !== 'controllers' && parentDir.toLowerCase() !== 'requests') {
+        return parentDir;
+      }
+      const baseName = parts[parts.length - 1]
+        .replace(/\.[^.]+$/, '')
+        .replace(/(Controller|Request|Resource|Policy|Observer|Event)$/i, '');
+      if (baseName.length > 2) return baseName;
+    }
+
+    // ── Strategy 5: Go package ──
+    if (lower.endsWith('.go')) {
+      const parentDir = parts[parts.length - 2];
+      if (parentDir && !this.layerClassifier.isGenericDir(parentDir.toLowerCase()) && parentDir !== 'cmd' && parentDir !== 'internal' && parentDir !== 'pkg') {
+        return parentDir;
+      }
+    }
+
+    // ── Strategy 6: Fallback — walk from end, find first non-generic dir ──
+    const extraGenericForFallback = new Set(['__pycache__', 'node_modules', 'dist', 'build', '.git', 'vendor', 'target']);
+    for (let i = parts.length - 2; i >= 0; i--) {
+      const dir = parts[i].toLowerCase();
+      if (
+        !this.layerClassifier.isGenericDir(dir) &&
+        !extraGenericForFallback.has(dir) &&
+        dir.length > 2 &&
+        !dir.startsWith('.') &&
+        !dir.startsWith('__')
+      ) {
+        return parts[i];
+      }
+    }
+
+    return null;
+  }
+
+
+public inferModulePath(filePath: string, moduleName: string): string {
+    const idx = filePath.toLowerCase().indexOf(moduleName.toLowerCase());
+    if (idx >= 0) {
+      return filePath.substring(0, idx + moduleName.length);
+    }
+    return filePath.split('/').slice(0, -1).join('/');
+  }
+
+
+}

package/src/core/agent-generator/framework-detector.ts

@@ -0,0 +1,66 @@
+import { AnalysisReport } from '../types/core.js';
+import { FrameworkInfo, DetectedToolchain } from './types/stack.js';
+import { PythonDetector } from './detectors/python-detector.js';
+import { NodeDetector } from './detectors/node-detector.js';
+import { JavaDetector } from './detectors/java-detector.js';
+import { PhpDetector } from './detectors/php-detector.js';
+import { GoDetector } from './detectors/go-detector.js';
+import { RubyDetector } from './detectors/ruby-detector.js';
+import { DartDetector } from './detectors/dart-detector.js';
+import { RustDetector } from './detectors/rust-detector.js';
+import { ToolchainDetector } from './detectors/toolchain-detector.js';
+import { StructureDetector } from './detectors/structure-detector.js';
+
+/**
+ * FrameworkDetector — Detects actual frameworks and toolchain from dependency files.
+ * Re-architected as a Strategy/Registry Facade.
+ */
+export class FrameworkDetector {
+  private detectors = [
+    new PythonDetector(),
+    new NodeDetector(),
+    new JavaDetector(),
+    new PhpDetector(),
+    new GoDetector(),
+    new RubyDetector(),
+    new DartDetector(),
+    new RustDetector()
+  ];
+  private toolchainDetector = new ToolchainDetector();
+  private structureDetector = new StructureDetector();
+
+  detect(projectPath: string, report: AnalysisReport): {
+    frameworks: FrameworkInfo[];
+    primaryFramework: FrameworkInfo | null;
+    toolchain: DetectedToolchain;
+    projectStructure: 'clean-architecture' | 'mvc' | 'modular' | 'flat' | 'monorepo' | 'unknown';
+  } {
+    const frameworks: FrameworkInfo[] = [];
+
+    // Run all detectors
+    for (const detector of this.detectors) {
+      detector.detect(projectPath, frameworks);
+    }
+
+    // Deduplicate by name
+    const seen = new Set<string>();
+    const unique = frameworks.filter(f => {
+      if (seen.has(f.name)) return false;
+      seen.add(f.name);
+      return true;
+    });
+
+    // Sort: web frameworks first, then by confidence
+    unique.sort((a, b) => {
+      if (a.category === 'web' && b.category !== 'web') return -1;
+      if (a.category !== 'web' && b.category === 'web') return 1;
+      return b.confidence - a.confidence;
+    });
+
+    const primaryFramework = unique.find(f => f.category === 'web') || null;
+    const toolchain = this.toolchainDetector.detectToolchain(projectPath, report, primaryFramework, unique);
+    const projectStructure = this.structureDetector.detectProjectStructure(report);
+
+    return { frameworks: unique, primaryFramework, toolchain, projectStructure };
+  }
+}

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

@@ -0,0 +1,55 @@
+import { join } from "path";
+import { existsSync } from "fs";
+import { AnalysisReport } from '../types/core.js';
+import { RefactoringPlan } from '../types/rules.js';
+import { StackInfo, FrameworkInfo, DetectedToolchain } from './types/stack.js';
+import { AgentAuditFinding, AgentItem, AgentItemStatus, AgentSuggestion, AgentGeneratorConfig, DEFAULT_AGENT_CONFIG } from './types/agent.js';
+import { TemplateContext, EnrichedTemplateContext } from './types/template.js';
+import { DomainInsights, ModuleDetail, DetectedEndpoint } from './types/domain.js';
+
+import { ContextBuilder } from "./engines/context-builder.js";
+import { AuditEngine } from "./engines/audit-engine.js";
+import { SuggestionEngine } from "./engines/suggestion-engine.js";
+import { GenerationEngine } from "./engines/generation-engine.js";
+import { StackDetector } from "./stack-detector.js";
+
+export type { StackInfo, AgentAuditFinding, AgentItem, AgentItemStatus, AgentSuggestion, EnrichedTemplateContext, DomainInsights, ModuleDetail, DetectedEndpoint, FrameworkInfo, DetectedToolchain };
+
+/**
+ * Agent Generator v3.2 — Enterprise-Grade
+ *
+ * Generates or audits .agent/ directories with enterprise-grade
+ * agent frameworks. Delegated to specialized engines.
+ */
+export class AgentGenerator {
+  private stackDetector = new StackDetector();
+  private contextBuilder = new ContextBuilder();
+  private auditEngine = new AuditEngine();
+  private suggestionEngine = new SuggestionEngine();
+  private generationEngine = new GenerationEngine();
+
+  suggest(report: AnalysisReport, plan: RefactoringPlan, projectPath: string): AgentSuggestion {
+    return this.suggestionEngine.suggest(report, plan, projectPath);
+  }
+
+  generate(
+    report: AnalysisReport,
+    plan: RefactoringPlan,
+    projectPath: string,
+    outputDir?: string
+  ): { generated: string[]; audit: AgentAuditFinding[] } {
+    const cleanReport = this.contextBuilder.sanitizeReport(report);
+    const stack = this.stackDetector.detect(cleanReport);
+    const agentDir = outputDir || join(projectPath, '.agent');
+    const isExisting = existsSync(agentDir);
+
+    if (isExisting) {
+      const audit = this.auditEngine.auditExisting(agentDir, stack, cleanReport, plan);
+      const generated = this.generationEngine.generateMissing(agentDir, audit, cleanReport, plan, stack, projectPath);
+      return { generated, audit };
+    }
+
+    const generated = this.generationEngine.generateFull(agentDir, cleanReport, plan, stack, projectPath);
+    return { generated, audit: [] };
+  }
+}

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

@@ -1,9 +1,11 @@
-import { AnalysisReport } from '../types.js';
-import { StackInfo } from './types.js';
+import { AnalysisReport } from '../types/core.js';
+import { StackInfo } from './types/stack.js';
 
 /**
  * Detects the technology stack from an AnalysisReport.
- * Extracted from the monolithic AgentGenerator for single-responsibility.
+ *
+ * v5.1: Uses report.projectInfo.frameworks (precise, from scanner v5.0)
+ * instead of naive string-matching on file paths.
  */
 export class StackDetector {
   detect(report: AnalysisReport): StackInfo {
@@ -29,34 +31,44 @@ export class StackDetector {
     if (extensions.has('php')) languages.add('PHP');
     if (extensions.has('cs')) languages.add('C#');
 
-    // ── Framework Detection from file patterns ──
-    const allFiles = files.join(' ');
-    if (allFiles.includes('manage.py') || allFiles.includes('django')) frameworks.add('Django');
-    if (allFiles.includes('flask') || allFiles.includes('app.py')) frameworks.add('Flask');
-    if (allFiles.includes('fastapi')) frameworks.add('FastAPI');
-    if (allFiles.includes('.module.ts') || allFiles.includes('nest')) frameworks.add('NestJS');
-    if (allFiles.includes('.component.ts') || allFiles.includes('angular')) frameworks.add('Angular');
-    if (allFiles.includes('.vue')) frameworks.add('Vue');
-    if (allFiles.includes('.tsx') && allFiles.includes('next')) frameworks.add('Next.js');
-    if (allFiles.includes('.dart')) frameworks.add('Flutter');
-    if (allFiles.includes('go.mod')) frameworks.add('Go Modules');
-    if (allFiles.includes('Cargo.toml')) frameworks.add('Cargo');
-    if (allFiles.includes('pom.xml') || allFiles.includes('build.gradle')) frameworks.add('Spring');
-    if (allFiles.includes('rails') || allFiles.includes('Gemfile')) frameworks.add('Rails');
-    if (allFiles.includes('laravel') || allFiles.includes('artisan')) frameworks.add('Laravel');
+    // ── Framework Detection: Trust report.projectInfo.frameworks ──
+    // These come from scanner v5.0 which reads actual package.json dependencies
+    const reportFrameworks = report.projectInfo?.frameworks || [];
+    for (const fw of reportFrameworks) {
+      frameworks.add(fw);
+    }
 
     // ── Derived Properties ──
     const primary = languages.size > 0 ? [...languages][0] : 'Unknown';
 
-    const hasBackend = languages.has('Python') || languages.has('TypeScript') ||
+    // Frontend frameworks that indicate hasFrontend
+    const FRONTEND_FRAMEWORKS = new Set([
+      'Angular', 'Vue', 'Vue.js', 'Next.js', 'React', 'Nuxt', 'Nuxt.js',
+      'Svelte', 'SvelteKit', 'Remix', 'Gatsby', 'Vite',
+    ]);
+
+    // Backend frameworks that indicate hasBackend (language-based is fallback)
+    const BACKEND_FRAMEWORKS = new Set([
+      'Express', 'Express.js', 'NestJS', 'Fastify', 'Koa', 'Hapi',
+      'Django', 'Flask', 'FastAPI', 'Spring Boot', 'Laravel', 'Rails',
+      'Ruby on Rails', 'Gin', 'Echo', 'Fiber', 'Actix Web', 'Rocket',
+      'Probot', 'MCP SDK',
+    ]);
+
+    const MOBILE_FRAMEWORKS = new Set(['Flutter', 'React Native', 'Expo']);
+
+    const hasBackend = [...frameworks].some(f => BACKEND_FRAMEWORKS.has(f)) ||
+      languages.has('Python') || languages.has('TypeScript') ||
       languages.has('Go') || languages.has('Java/Kotlin') || languages.has('Ruby') ||
       languages.has('PHP') || languages.has('C#') || languages.has('Rust');
 
-    const hasFrontend = frameworks.has('Angular') || frameworks.has('Vue') ||
-      frameworks.has('Next.js') || frameworks.has('React') || extensions.has('html');
+    const hasFrontend = [...frameworks].some(f => FRONTEND_FRAMEWORKS.has(f)) ||
+      extensions.has('tsx') || extensions.has('jsx');
 
-    const hasMobile = languages.has('Dart') || frameworks.has('Flutter');
+    const hasMobile = [...frameworks].some(f => MOBILE_FRAMEWORKS.has(f)) ||
+      languages.has('Dart');
 
+    const allFiles = files.join(' ').toLowerCase();
     const hasDatabase = allFiles.includes('migration') || allFiles.includes('entity') ||
       allFiles.includes('model') || allFiles.includes('schema') ||
       allFiles.includes('prisma') || allFiles.includes('typeorm');

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

@@ -1,4 +1,4 @@
-import { TemplateContext, EnrichedTemplateContext } from '../../types.js';
+import { TemplateContext, EnrichedTemplateContext } from '../../types/template.js';
 import { crossRef, depthIndicator, depthAtLeast, getEnriched, frameworkBadge, frameworkModuleStructure, frameworkSecurityChecklist, toolchainCommands, projectStructureBadge } from '../template-helpers.js';
 
 /**
@@ -148,8 +148,11 @@ ${crossRef('backend', ctx)}
 export function generateFrontendAgent(ctx: TemplateContext | EnrichedTemplateContext): string {
   const { stack, projectName, config, report } = ctx;
   const enriched = getEnriched(ctx);
-  const fw = stack.frameworks.find(f =>
-    ['Angular', 'Vue', 'Next.js', 'React'].includes(f)) || 'Frontend';
+  // v5.1: Use enriched primaryFramework or detect from all frameworks
+  const FRONTEND_FWS = ['Angular', 'Vue', 'Vue.js', 'Next.js', 'React', 'Nuxt', 'Svelte', 'Remix'];
+  const detectedFw = enriched.detectedFrameworks?.find(f => FRONTEND_FWS.includes(f.name));
+  const fw = detectedFw?.name ||
+    stack.frameworks.find(f => FRONTEND_FWS.includes(f)) || 'Frontend';
 
   // Build endpoints integration guide if available
   const endpointsGuide = enriched.endpoints && enriched.endpoints.length > 0

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

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 
 /**
  * Generates 01-architecture.md — layer rules, dependency direction,

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

@@ -1,4 +1,4 @@
-import { TemplateContext } from '../../types.js';
+import { TemplateContext } from '../../types/template.js';
 import { getEnriched } from '../template-helpers.js';
 
 /**