@girardelli/architect 1.1.0

package/src/reporter.ts

@@ -0,0 +1,166 @@
+import { AnalysisReport } from './types.js';
+
+export class ReportGenerator {
+  generateMarkdownReport(report: AnalysisReport): string {
+    let markdown = '';
+
+    markdown += this.generateHeader(report);
+    markdown += this.generateProjectSummary(report);
+    markdown += this.generateScoreSection(report);
+    markdown += this.generateAntiPatternsSection(report);
+    markdown += this.generateLayersSection(report);
+    markdown += this.generateDiagramSection(report);
+    markdown += this.generateSuggestionsSection(report);
+
+    return markdown;
+  }
+
+  private generateHeader(report: AnalysisReport): string {
+    const timestamp = new Date(report.timestamp).toLocaleString();
+    let header = '# Architecture Analysis Report\n\n';
+    header += `Generated: ${timestamp}\n`;
+    header += `Project: ${report.projectInfo.name}\n`;
+    header += `Path: ${report.projectInfo.path}\n\n`;
+    return header;
+  }
+
+  private generateProjectSummary(report: AnalysisReport): string {
+    let summary = '## Project Summary\n\n';
+    summary += `| Metric | Value |\n`;
+    summary += `|--------|-------|\n`;
+    summary += `| Total Files | ${report.projectInfo.totalFiles} |\n`;
+    summary += `| Lines of Code | ${report.projectInfo.totalLines.toLocaleString()} |\n`;
+    summary += `| Primary Languages | ${report.projectInfo.primaryLanguages.join(', ') || 'N/A'} |\n`;
+    summary += `| Frameworks | ${report.projectInfo.frameworks.join(', ') || 'None detected'} |\n\n`;
+    return summary;
+  }
+
+  private generateScoreSection(report: AnalysisReport): string {
+    let section = '## Architecture Quality Score\n\n';
+    section += `### Overall Score: **${report.score.overall}/100**\n\n`;
+
+    section += 'Component Breakdown:\n\n';
+    for (const component of report.score.components) {
+      section += `- **${component.name}**: ${component.score}/100 (weight: ${(component.weight * 100).toFixed(0)}%)\n`;
+      section += `  ${component.explanation}\n\n`;
+    }
+
+    return section;
+  }
+
+  private generateAntiPatternsSection(report: AnalysisReport): string {
+    let section = '## Anti-Patterns Detected\n\n';
+
+    if (report.antiPatterns.length === 0) {
+      section += 'No significant anti-patterns detected. Excellent architecture!\n\n';
+      return section;
+    }
+
+    section += `Found **${report.antiPatterns.length}** anti-pattern(s):\n\n`;
+
+    for (const pattern of report.antiPatterns) {
+      const severityEmoji: Record<string, string> = {
+        CRITICAL: 'X',
+        HIGH: 'W',
+        MEDIUM: 'o',
+        LOW: '-',
+      };
+      const emoji = severityEmoji[pattern.severity] || 'o';
+
+      section += `### ${emoji} ${pattern.name} [${pattern.severity}]\n\n`;
+      section += `**Location**: \`${pattern.location}\`\n\n`;
+      section += `**Description**: ${pattern.description}\n\n`;
+      section += `**Suggestion**: ${pattern.suggestion}\n\n`;
+
+      if (pattern.metrics && Object.keys(pattern.metrics).length > 0) {
+        section += '**Metrics**:\n';
+        for (const [key, value] of Object.entries(pattern.metrics)) {
+          section += `- ${key}: ${value}\n`;
+        }
+        section += '\n';
+      }
+    }
+
+    return section;
+  }
+
+  private generateLayersSection(report: AnalysisReport): string {
+    let section = '## Architectural Layers\n\n';
+
+    if (report.layers.length === 0) {
+      section += 'No layers detected.\n\n';
+      return section;
+    }
+
+    for (const layer of report.layers) {
+      section += `### ${layer.name} Layer\n\n`;
+      section += `${layer.description}\n\n`;
+      section += `**Files**: ${layer.files.length}\n`;
+      section += '```\n';
+      for (const file of layer.files.slice(0, 5)) {
+        section += `${file}\n`;
+      }
+      if (layer.files.length > 5) {
+        section += `... and ${layer.files.length - 5} more files\n`;
+      }
+      section += '```\n\n';
+    }
+
+    return section;
+  }
+
+  private generateDiagramSection(report: AnalysisReport): string {
+    let section = '## Architecture Diagram\n\n';
+    section += `Type: ${report.diagram.type}\n\n`;
+    section += '```mermaid\n';
+    section += report.diagram.mermaid;
+    section += '\n```\n\n';
+    return section;
+  }
+
+  private generateSuggestionsSection(report: AnalysisReport): string {
+    let section = '## Refactoring Suggestions\n\n';
+
+    if (report.suggestions.length === 0) {
+      section += 'No immediate refactoring suggestions.\n\n';
+      return section;
+    }
+
+    const bySeverity = this.groupBySeverity(report.suggestions);
+
+    for (const severity of ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW']) {
+      const suggestions = bySeverity[severity];
+      if (!suggestions || suggestions.length === 0) continue;
+
+      section += `### ${severity} Priority\n\n`;
+
+      for (let i = 0; i < suggestions.length; i++) {
+        const suggestion = suggestions[i];
+        section += `${i + 1}. **${suggestion.title}**\n`;
+        section += `   ${suggestion.description}\n`;
+        section += `   Impact: ${suggestion.impact}\n\n`;
+      }
+    }
+
+    return section;
+  }
+
+  private groupBySeverity(
+    suggestions: Array<{ priority: string; title: string; description: string; impact: string }>
+  ): Record<string, typeof suggestions> {
+    const grouped: Record<string, typeof suggestions> = {
+      CRITICAL: [],
+      HIGH: [],
+      MEDIUM: [],
+      LOW: [],
+    };
+
+    for (const suggestion of suggestions) {
+      if (grouped[suggestion.priority]) {
+        grouped[suggestion.priority].push(suggestion);
+      }
+    }
+
+    return grouped;
+  }
+}

package/src/scanner.ts

@@ -0,0 +1,298 @@
+import { globSync } from 'glob';
+import { readFileSync, lstatSync } from 'fs';
+import { join, relative, extname } from 'path';
+import { FileNode, ProjectInfo, ArchitectConfig } from './types.js';
+
+export class ProjectScanner {
+  private projectPath: string;
+  private config: ArchitectConfig;
+  private frameworks: Set<string> = new Set();
+
+  constructor(projectPath: string, config: ArchitectConfig) {
+    this.projectPath = projectPath;
+    this.config = config;
+  }
+
+  scan(): ProjectInfo {
+    const files = this.scanDirectory();
+    const fileTree = this.buildFileTree(files);
+
+    // Detect frameworks from scanned files AND parent package.json
+    const parentPackageJsons = this.findParentPackageJsons();
+    const allFilesForDetection = [...files, ...parentPackageJsons];
+    const frameworks = this.detectFrameworks(allFilesForDetection);
+
+    const languages = this.detectLanguages(files);
+    const totalLines = this.countTotalLines(files);
+    const projectName = this.resolveProjectName(parentPackageJsons);
+
+    return {
+      path: this.projectPath,
+      name: projectName,
+      frameworks: Array.from(frameworks),
+      totalFiles: files.length,
+      totalLines,
+      primaryLanguages: languages,
+      fileTree,
+    };
+  }
+
+  /**
+   * Walk up directory tree to find package.json files for project name and framework detection
+   */
+  private findParentPackageJsons(): string[] {
+    const found: string[] = [];
+    let dir = this.projectPath;
+    const root = '/';
+    let depth = 0;
+
+    while (dir !== root && depth < 5) {
+      const pkgPath = join(dir, 'package.json');
+      try {
+        readFileSync(pkgPath, 'utf-8');
+        found.push(pkgPath);
+      } catch {
+        // no package.json here
+      }
+      dir = join(dir, '..');
+      depth++;
+    }
+
+    return found;
+  }
+
+  /**
+   * Resolve project name from nearest package.json or directory name
+   */
+  private resolveProjectName(packageJsonPaths: string[]): string {
+    for (const pkgPath of packageJsonPaths) {
+      try {
+        const content = readFileSync(pkgPath, 'utf-8');
+        const parsed = JSON.parse(content);
+        if (parsed.name) {
+          return parsed.name;
+        }
+      } catch {
+        // skip
+      }
+    }
+    return this.projectPath.split('/').pop() || 'project';
+  }
+
+  private scanDirectory(): string[] {
+    const ignorePatterns = this.config.ignore || [];
+    const negatedPatterns = ignorePatterns.map((p) => `!**/${p}/**`);
+
+    const files = globSync('**/*', {
+      cwd: this.projectPath,
+      ignore: ignorePatterns,
+      absolute: true,
+      nodir: true,
+    });
+
+    return files.filter(
+      (f) =>
+        !lstatSync(f).isDirectory() && this.isSourceFile(f)
+    );
+  }
+
+  private isSourceFile(filePath: string): boolean {
+    const ext = extname(filePath).toLowerCase();
+    const sourceExtensions = [
+      '.js',
+      '.ts',
+      '.tsx',
+      '.jsx',
+      '.py',
+      '.java',
+      '.go',
+      '.rb',
+      '.php',
+      '.cs',
+      '.cpp',
+      '.c',
+      '.h',
+      '.rs',
+      '.kt',
+      '.scala',
+      '.groovy',
+      '.sql',
+      '.graphql',
+      '.json',
+      '.yaml',
+      '.yml',
+      '.xml',
+    ];
+    return sourceExtensions.includes(ext);
+  }
+
+  private buildFileTree(files: string[]): FileNode {
+    const root: FileNode = {
+      path: this.projectPath,
+      name: this.projectPath.split('/').pop() || 'root',
+      type: 'directory',
+    };
+
+    for (const file of files) {
+      const relativePath = relative(this.projectPath, file);
+      const parts = relativePath.split('/');
+      let current = root;
+
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        const isFile = i === parts.length - 1;
+
+        let child = (current.children || []).find((c) => c.name === part);
+        if (!child) {
+          child = {
+            path: join(current.path, part),
+            name: part,
+            type: isFile ? 'file' : 'directory',
+            extension: isFile ? extname(part) : undefined,
+          };
+
+          if (isFile) {
+            child.lines = this.countLines(file);
+            child.language = this.detectLanguage(file);
+          }
+
+          if (!current.children) current.children = [];
+          current.children.push(child);
+        }
+
+        current = child;
+      }
+    }
+
+    return root;
+  }
+
+  private detectFrameworks(files: string[]): Set<string> {
+    const frameworks = new Set<string>();
+
+    for (const file of files) {
+      if (file.endsWith('package.json')) {
+        try {
+          const content = readFileSync(file, 'utf-8');
+          const parsed = JSON.parse(content);
+          const allDeps = {
+            ...parsed.dependencies,
+            ...parsed.devDependencies,
+          };
+
+          // Detect from actual dependency keys
+          if (allDeps['@nestjs/core'] || allDeps['@nestjs/common']) frameworks.add('NestJS');
+          if (allDeps['react'] || allDeps['react-dom']) frameworks.add('React');
+          if (allDeps['@angular/core']) frameworks.add('Angular');
+          if (allDeps['vue'] || allDeps['@vue/core']) frameworks.add('Vue.js');
+          if (allDeps['express']) frameworks.add('Express.js');
+          if (allDeps['next']) frameworks.add('Next.js');
+          if (allDeps['fastify']) frameworks.add('Fastify');
+          if (allDeps['typeorm']) frameworks.add('TypeORM');
+          if (allDeps['prisma'] || allDeps['@prisma/client']) frameworks.add('Prisma');
+          if (allDeps['sequelize']) frameworks.add('Sequelize');
+          if (allDeps['mongoose']) frameworks.add('Mongoose');
+        } catch {
+          // Fallback: simple string matching
+          try {
+            const content = readFileSync(file, 'utf-8');
+            if (content.includes('@nestjs')) frameworks.add('NestJS');
+            if (content.includes('react')) frameworks.add('React');
+            if (content.includes('angular')) frameworks.add('Angular');
+            if (content.includes('vue')) frameworks.add('Vue.js');
+            if (content.includes('express')) frameworks.add('Express.js');
+            if (content.includes('next')) frameworks.add('Next.js');
+          } catch {
+            // skip
+          }
+        }
+      }
+
+      if (file.includes('pom.xml')) {
+        try {
+          const content = readFileSync(file, 'utf-8');
+          if (content.includes('spring-boot')) frameworks.add('Spring Boot');
+          if (content.includes('spring')) frameworks.add('Spring');
+        } catch {
+          // skip
+        }
+      }
+
+      if (file.includes('requirements.txt')) {
+        try {
+          const content = readFileSync(file, 'utf-8');
+          if (content.includes('django')) frameworks.add('Django');
+          if (content.includes('flask')) frameworks.add('Flask');
+          if (content.includes('fastapi')) frameworks.add('FastAPI');
+        } catch {
+          // skip
+        }
+      }
+
+      if (file.includes('Gemfile')) {
+        try {
+          const content = readFileSync(file, 'utf-8');
+          if (content.includes('rails')) frameworks.add('Ruby on Rails');
+        } catch {
+          // skip
+        }
+      }
+
+      if (file.includes('go.mod')) {
+        frameworks.add('Go');
+      }
+    }
+
+    return frameworks;
+  }
+
+  private detectLanguages(files: string[]): string[] {
+    const languages = new Set<string>();
+
+    for (const file of files) {
+      const lang = this.detectLanguage(file);
+      if (lang && lang !== 'Unknown') languages.add(lang);
+    }
+
+    return Array.from(languages);
+  }
+
+  private detectLanguage(filePath: string): string {
+    const ext = extname(filePath).toLowerCase();
+
+    const languageMap: Record<string, string> = {
+      '.js': 'JavaScript',
+      '.ts': 'TypeScript',
+      '.tsx': 'TypeScript',
+      '.jsx': 'JavaScript',
+      '.py': 'Python',
+      '.java': 'Java',
+      '.go': 'Go',
+      '.rb': 'Ruby',
+      '.php': 'PHP',
+      '.cs': 'C#',
+      '.cpp': 'C++',
+      '.c': 'C',
+      '.rs': 'Rust',
+      '.kt': 'Kotlin',
+      '.scala': 'Scala',
+      '.sql': 'SQL',
+      '.graphql': 'GraphQL',
+    };
+
+    return languageMap[ext] || 'Unknown';
+  }
+
+  private countLines(filePath: string): number {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      return content.split('\n').length;
+    } catch {
+      return 0;
+    }
+  }
+
+  private countTotalLines(files: string[]): number {
+    return files.reduce((total, file) => total + this.countLines(file), 0);
+  }
+}

package/src/scorer.ts

@@ -0,0 +1,193 @@
+import { ArchitectureScore, DependencyEdge, AntiPattern, ScoreComponent } from './types.js';
+
+export class ArchitectureScorer {
+  private modularity: number = 0;
+  private coupling: number = 0;
+  private cohesion: number = 0;
+  private layering: number = 0;
+
+  score(
+    edges: DependencyEdge[],
+    antiPatterns: AntiPattern[],
+    totalFiles: number
+  ): ArchitectureScore {
+    this.calculateModularity(edges, totalFiles);
+    this.calculateCoupling(edges, totalFiles);
+    this.calculateCohesion(edges);
+    this.calculateLayering(antiPatterns);
+
+    const components = [
+      {
+        name: 'Modularity',
+        score: Math.round(this.modularity),
+        maxScore: 100,
+        weight: 0.4,
+        explanation:
+          'Measures appropriate module boundaries and single responsibility principle adherence',
+      },
+      {
+        name: 'Coupling',
+        score: Math.round(this.coupling),
+        maxScore: 100,
+        weight: 0.25,
+        explanation:
+          'Evaluates interdependencies between modules; lower coupling is better',
+      },
+      {
+        name: 'Cohesion',
+        score: Math.round(this.cohesion),
+        maxScore: 100,
+        weight: 0.2,
+        explanation:
+          'Assesses how closely related functionality is grouped together',
+      },
+      {
+        name: 'Layering',
+        score: Math.round(this.layering),
+        maxScore: 100,
+        weight: 0.15,
+        explanation: 'Checks adherence to architectural layer separation',
+      },
+    ];
+
+    const overall = Math.round(
+      components[0].score * components[0].weight +
+        components[1].score * components[1].weight +
+        components[2].score * components[2].weight +
+        components[3].score * components[3].weight
+    );
+
+    return {
+      overall: Math.min(100, Math.max(0, overall)),
+      components,
+      breakdown: {
+        modularity: Math.round(this.modularity),
+        coupling: Math.round(this.coupling),
+        cohesion: Math.round(this.cohesion),
+        layering: Math.round(this.layering),
+      },
+    };
+  }
+
+  private calculateModularity(edges: DependencyEdge[], totalFiles: number): void {
+    if (totalFiles === 0) {
+      this.modularity = 50;
+      return;
+    }
+
+    const avgEdgesPerFile = edges.length / totalFiles;
+
+    if (avgEdgesPerFile < 2) {
+      this.modularity = 95;
+    } else if (avgEdgesPerFile < 4) {
+      this.modularity = 85;
+    } else if (avgEdgesPerFile < 6) {
+      this.modularity = 70;
+    } else if (avgEdgesPerFile < 10) {
+      this.modularity = 50;
+    } else {
+      this.modularity = 30;
+    }
+  }
+
+  private calculateCoupling(edges: DependencyEdge[], totalFiles: number): void {
+    if (totalFiles === 0) {
+      this.coupling = 50;
+      return;
+    }
+
+    const nodeWithMaxEdges = this.findNodeWithMaxEdges(edges);
+    const maxEdgeCount = nodeWithMaxEdges ? nodeWithMaxEdges.count : 0;
+
+    const couplingRatio = maxEdgeCount / (totalFiles - 1);
+
+    if (couplingRatio < 0.2) {
+      this.coupling = 95;
+    } else if (couplingRatio < 0.4) {
+      this.coupling = 85;
+    } else if (couplingRatio < 0.6) {
+      this.coupling = 70;
+    } else if (couplingRatio < 0.8) {
+      this.coupling = 50;
+    } else {
+      this.coupling = 30;
+    }
+  }
+
+  private findNodeWithMaxEdges(
+    edges: DependencyEdge[]
+  ): { node: string; count: number } | null {
+    const nodeEdgeCount: Record<string, number> = {};
+
+    for (const edge of edges) {
+      nodeEdgeCount[edge.from] = (nodeEdgeCount[edge.from] || 0) + 1;
+      nodeEdgeCount[edge.to] = (nodeEdgeCount[edge.to] || 0) + 1;
+    }
+
+    let maxNode: string | null = null;
+    let maxCount = 0;
+
+    for (const [node, count] of Object.entries(nodeEdgeCount)) {
+      if (count > maxCount) {
+        maxCount = count;
+        maxNode = node;
+      }
+    }
+
+    return maxNode ? { node: maxNode, count: maxCount } : null;
+  }
+
+  private calculateCohesion(edges: DependencyEdge[]): void {
+    if (edges.length === 0) {
+      this.cohesion = 50;
+      return;
+    }
+
+    const internalEdges = edges.filter((e) =>
+      this.isInternalDependency(e.from, e.to)
+    ).length;
+
+    const cohesionRatio = internalEdges / edges.length;
+
+    if (cohesionRatio > 0.7) {
+      this.cohesion = 95;
+    } else if (cohesionRatio > 0.5) {
+      this.cohesion = 80;
+    } else if (cohesionRatio > 0.3) {
+      this.cohesion = 65;
+    } else if (cohesionRatio > 0.1) {
+      this.cohesion = 45;
+    } else {
+      this.cohesion = 30;
+    }
+  }
+
+  private isInternalDependency(from: string, to: string): boolean {
+    const fromModule = from.split('/').slice(0, -1).join('/');
+    const toModule = to.split('/').slice(0, -1).join('/');
+    return fromModule === toModule;
+  }
+
+  private calculateLayering(antiPatterns: AntiPattern[]): void {
+    const layeringViolations = antiPatterns.filter(
+      (p) =>
+        p.name === 'Leaky Abstraction' ||
+        p.name === 'Shotgun Surgery' ||
+        p.name === 'Circular Dependency'
+    ).length;
+
+    if (layeringViolations === 0) {
+      this.layering = 95;
+    } else if (layeringViolations === 1) {
+      this.layering = 85;
+    } else if (layeringViolations === 2) {
+      this.layering = 70;
+    } else if (layeringViolations === 3) {
+      this.layering = 55;
+    } else if (layeringViolations <= 5) {
+      this.layering = 40;
+    } else {
+      this.layering = 25;
+    }
+  }
+}