@aiready/consistency 0.2.0

package/src/analyzer.ts

@@ -0,0 +1,182 @@
+import { scanFiles } from '@aiready/core';
+import type { AnalysisResult, Issue } from '@aiready/core';
+import type { ConsistencyOptions, ConsistencyReport, ConsistencyIssue } from './types';
+import { analyzeNaming, detectNamingConventions } from './analyzers/naming';
+import { analyzePatterns } from './analyzers/patterns';
+
+/**
+ * Main consistency analyzer that orchestrates all analysis types
+ */
+export async function analyzeConsistency(
+  options: ConsistencyOptions
+): Promise<ConsistencyReport> {
+  const {
+    checkNaming = true,
+    checkPatterns = true,
+    checkArchitecture = false, // Not implemented yet
+    minSeverity = 'info',
+    ...scanOptions
+  } = options;
+
+  // Scan files
+  const filePaths = await scanFiles(scanOptions);
+
+  // Collect issues by category
+  const namingIssues = checkNaming ? await analyzeNaming(filePaths) : [];
+  const patternIssues = checkPatterns ? await analyzePatterns(filePaths) : [];
+
+  // Convert to AnalysisResult format
+  const results: AnalysisResult[] = [];
+  const fileIssuesMap = new Map<string, ConsistencyIssue[]>();
+
+  // Process naming issues
+  for (const issue of namingIssues) {
+    if (!shouldIncludeSeverity(issue.severity, minSeverity)) {
+      continue;
+    }
+
+    const consistencyIssue: ConsistencyIssue = {
+      type: issue.type === 'convention-mix' ? 'naming-inconsistency' : 'naming-quality',
+      category: 'naming',
+      severity: issue.severity,
+      message: `${issue.type}: ${issue.identifier}`,
+      location: {
+        file: issue.file,
+        line: issue.line,
+        column: issue.column
+      },
+      suggestion: issue.suggestion
+    };
+
+    if (!fileIssuesMap.has(issue.file)) {
+      fileIssuesMap.set(issue.file, []);
+    }
+    fileIssuesMap.get(issue.file)!.push(consistencyIssue);
+  }
+
+  // Process pattern issues
+  for (const issue of patternIssues) {
+    if (!shouldIncludeSeverity(issue.severity, minSeverity)) {
+      continue;
+    }
+
+    const consistencyIssue: ConsistencyIssue = {
+      type: 'pattern-inconsistency',
+      category: 'patterns',
+      severity: issue.severity,
+      message: issue.description,
+      location: {
+        file: issue.files[0] || 'multiple files',
+        line: 1
+      },
+      examples: issue.examples,
+      suggestion: `Standardize ${issue.type} patterns across ${issue.files.length} files`
+    };
+
+    // Add to first file in the pattern
+    const firstFile = issue.files[0];
+    if (firstFile && !fileIssuesMap.has(firstFile)) {
+      fileIssuesMap.set(firstFile, []);
+    }
+    if (firstFile) {
+      fileIssuesMap.get(firstFile)!.push(consistencyIssue);
+    }
+  }
+
+  // Convert to AnalysisResult format
+  for (const [fileName, issues] of fileIssuesMap) {
+    results.push({
+      fileName,
+      issues: issues as Issue[],
+      metrics: {
+        consistencyScore: calculateConsistencyScore(issues)
+      }
+    });
+  }
+
+  // Generate recommendations
+  const recommendations = generateRecommendations(namingIssues, patternIssues);
+
+  // Detect naming conventions
+  const conventionAnalysis = detectNamingConventions(filePaths, namingIssues);
+
+  return {
+    summary: {
+      totalIssues: namingIssues.length + patternIssues.length,
+      namingIssues: namingIssues.length,
+      patternIssues: patternIssues.length,
+      architectureIssues: 0,
+      filesAnalyzed: filePaths.length
+    },
+    results,
+    recommendations
+  };
+}
+
+function shouldIncludeSeverity(
+  severity: 'critical' | 'major' | 'minor' | 'info',
+  minSeverity: 'critical' | 'major' | 'minor' | 'info'
+): boolean {
+  const severityLevels = { info: 0, minor: 1, major: 2, critical: 3 };
+  return severityLevels[severity] >= severityLevels[minSeverity];
+}
+
+function calculateConsistencyScore(issues: ConsistencyIssue[]): number {
+  // Higher score = more consistent (fewer issues)
+  const weights = { critical: 10, major: 5, minor: 2, info: 1 };
+  const totalWeight = issues.reduce((sum, issue) => sum + weights[issue.severity], 0);
+  // Score from 0-1, where 1 is perfect
+  return Math.max(0, 1 - totalWeight / 100);
+}
+
+function generateRecommendations(
+  namingIssues: any[],
+  patternIssues: any[]
+): string[] {
+  const recommendations: string[] = [];
+
+  if (namingIssues.length > 0) {
+    const conventionMixCount = namingIssues.filter(i => i.type === 'convention-mix').length;
+    if (conventionMixCount > 0) {
+      recommendations.push(
+        `Standardize naming conventions: Found ${conventionMixCount} snake_case variables in TypeScript/JavaScript (use camelCase)`
+      );
+    }
+
+    const poorNamingCount = namingIssues.filter(i => i.type === 'poor-naming').length;
+    if (poorNamingCount > 0) {
+      recommendations.push(
+        `Improve variable naming: Found ${poorNamingCount} single-letter or unclear variable names`
+      );
+    }
+  }
+
+  if (patternIssues.length > 0) {
+    const errorHandlingIssues = patternIssues.filter(i => i.type === 'error-handling');
+    if (errorHandlingIssues.length > 0) {
+      recommendations.push(
+        'Standardize error handling strategy across the codebase (prefer try-catch with typed errors)'
+      );
+    }
+
+    const asyncIssues = patternIssues.filter(i => i.type === 'async-style');
+    if (asyncIssues.length > 0) {
+      recommendations.push(
+        'Use async/await consistently instead of mixing with promise chains or callbacks'
+      );
+    }
+
+    const importIssues = patternIssues.filter(i => i.type === 'import-style');
+    if (importIssues.length > 0) {
+      recommendations.push(
+        'Use ES modules consistently across the project (avoid mixing with CommonJS)'
+      );
+    }
+  }
+
+  if (recommendations.length === 0) {
+    recommendations.push('No major consistency issues found! Your codebase follows good practices.');
+  }
+
+  return recommendations;
+}

package/src/analyzers/naming.ts

@@ -0,0 +1,134 @@
+import { readFileContent } from '@aiready/core';
+import type { NamingIssue } from '../types';
+
+/**
+ * Analyzes naming conventions and quality
+ */
+export async function analyzeNaming(files: string[]): Promise<NamingIssue[]> {
+  const issues: NamingIssue[] = [];
+
+  for (const file of files) {
+    const content = await readFileContent(file);
+    const fileIssues = analyzeFileNaming(file, content);
+    issues.push(...fileIssues);
+  }
+
+  return issues;
+}
+
+function analyzeFileNaming(file: string, content: string): NamingIssue[] {
+  const issues: NamingIssue[] = [];
+
+  // Split into lines for line number tracking
+  const lines = content.split('\n');
+
+  // Check for naming patterns
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+
+    // Check for single letter variables (except i, j, k in loops)
+    const singleLetterMatches = line.matchAll(/\b(?:const|let|var)\s+([a-hm-z])\s*=/gi);
+    for (const match of singleLetterMatches) {
+      issues.push({
+        file,
+        line: lineNumber,
+        type: 'poor-naming',
+        identifier: match[1],
+        severity: 'minor',
+        suggestion: `Use descriptive variable name instead of single letter '${match[1]}'`
+      });
+    }
+
+    // Check for overly abbreviated variables
+    const abbreviationMatches = line.matchAll(/\b(?:const|let|var)\s+([a-z]{1,3})(?=[A-Z]|_|\s*=)/g);
+    for (const match of abbreviationMatches) {
+      const abbrev = match[1];
+      // Skip common acceptable abbreviations
+      if (!['id', 'url', 'api', 'db', 'fs', 'os', 'ui'].includes(abbrev.toLowerCase())) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: 'abbreviation',
+          identifier: abbrev,
+          severity: 'info',
+          suggestion: `Consider using full word instead of abbreviation '${abbrev}'`
+        });
+      }
+    }
+
+    // Check for snake_case vs camelCase mixing in TypeScript/JavaScript
+    if (file.match(/\.(ts|tsx|js|jsx)$/)) {
+      const camelCaseVars = line.match(/\b(?:const|let|var)\s+([a-z][a-zA-Z0-9]*)\s*=/);
+      const snakeCaseVars = line.match(/\b(?:const|let|var)\s+([a-z][a-z0-9]*_[a-z0-9_]*)\s*=/);
+      
+      if (snakeCaseVars) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: 'convention-mix',
+          identifier: snakeCaseVars[1],
+          severity: 'minor',
+          suggestion: `Use camelCase '${snakeCaseToCamelCase(snakeCaseVars[1])}' instead of snake_case in TypeScript/JavaScript`
+        });
+      }
+    }
+
+    // Check for unclear boolean names (should start with is/has/should/can)
+    const booleanMatches = line.matchAll(/\b(?:const|let|var)\s+([a-z][a-zA-Z0-9]*)\s*:\s*boolean/gi);
+    for (const match of booleanMatches) {
+      const name = match[1];
+      if (!name.match(/^(is|has|should|can|will|did)/i)) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: 'unclear',
+          identifier: name,
+          severity: 'info',
+          suggestion: `Boolean variable '${name}' should start with is/has/should/can for clarity`
+        });
+      }
+    }
+
+    // Check for function names that don't indicate action
+    const functionMatches = line.matchAll(/function\s+([a-z][a-zA-Z0-9]*)/g);
+    for (const match of functionMatches) {
+      const name = match[1];
+      // Functions should typically start with verbs
+      if (!name.match(/^(get|set|is|has|can|should|create|update|delete|fetch|load|save|process|handle|validate|check|find|search|filter|map|reduce)/)) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: 'unclear',
+          identifier: name,
+          severity: 'info',
+          suggestion: `Function '${name}' should start with an action verb (get, set, create, etc.)`
+        });
+      }
+    }
+  });
+
+  return issues;
+}
+
+function snakeCaseToCamelCase(str: string): string {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+/**
+ * Detects naming convention patterns across the codebase
+ */
+export function detectNamingConventions(files: string[], allIssues: NamingIssue[]): {
+  dominantConvention: 'camelCase' | 'snake_case' | 'PascalCase' | 'mixed';
+  conventionScore: number;
+} {
+  // Count conventions
+  const camelCaseCount = allIssues.filter(i => i.type === 'convention-mix').length;
+  const totalChecks = files.length * 10; // Rough estimate
+
+  if (camelCaseCount / totalChecks > 0.3) {
+    return { dominantConvention: 'mixed', conventionScore: 0.5 };
+  }
+
+  // For TypeScript/JavaScript, default to camelCase
+  return { dominantConvention: 'camelCase', conventionScore: 0.9 };
+}

package/src/analyzers/patterns.ts

@@ -0,0 +1,192 @@
+import { readFileContent } from '@aiready/core';
+import type { PatternIssue } from '../types';
+
+/**
+ * Analyzes code pattern consistency
+ */
+export async function analyzePatterns(files: string[]): Promise<PatternIssue[]> {
+  const issues: PatternIssue[] = [];
+
+  // Analyze error handling patterns
+  const errorHandlingIssues = await analyzeErrorHandling(files);
+  issues.push(...errorHandlingIssues);
+
+  // Analyze async/await patterns
+  const asyncIssues = await analyzeAsyncPatterns(files);
+  issues.push(...asyncIssues);
+
+  // Analyze import styles
+  const importIssues = await analyzeImportStyles(files);
+  issues.push(...importIssues);
+
+  return issues;
+}
+
+async function analyzeErrorHandling(files: string[]): Promise<PatternIssue[]> {
+  const patterns = {
+    tryCatch: [] as string[],
+    throwsError: [] as string[],
+    returnsNull: [] as string[],
+    returnsError: [] as string[]
+  };
+
+  for (const file of files) {
+    const content = await readFileContent(file);
+    
+    if (content.includes('try {') || content.includes('} catch')) {
+      patterns.tryCatch.push(file);
+    }
+    if (content.match(/throw new \w*Error/)) {
+      patterns.throwsError.push(file);
+    }
+    if (content.match(/return null/)) {
+      patterns.returnsNull.push(file);
+    }
+    if (content.match(/return \{ error:/)) {
+      patterns.returnsError.push(file);
+    }
+  }
+
+  const issues: PatternIssue[] = [];
+
+  // Check for mixed error handling strategies
+  const strategiesUsed = Object.values(patterns).filter(p => p.length > 0).length;
+  if (strategiesUsed > 2) {
+    issues.push({
+      files: [...new Set([
+        ...patterns.tryCatch,
+        ...patterns.throwsError,
+        ...patterns.returnsNull,
+        ...patterns.returnsError
+      ])],
+      type: 'error-handling',
+      description: 'Inconsistent error handling strategies across codebase',
+      examples: [
+        patterns.tryCatch.length > 0 ? `Try-catch used in ${patterns.tryCatch.length} files` : '',
+        patterns.throwsError.length > 0 ? `Throws errors in ${patterns.throwsError.length} files` : '',
+        patterns.returnsNull.length > 0 ? `Returns null in ${patterns.returnsNull.length} files` : '',
+        patterns.returnsError.length > 0 ? `Returns error objects in ${patterns.returnsError.length} files` : ''
+      ].filter(e => e),
+      severity: 'major'
+    });
+  }
+
+  return issues;
+}
+
+async function analyzeAsyncPatterns(files: string[]): Promise<PatternIssue[]> {
+  const patterns = {
+    asyncAwait: [] as string[],
+    promises: [] as string[],
+    callbacks: [] as string[]
+  };
+
+  for (const file of files) {
+    const content = await readFileContent(file);
+    
+    if (content.match(/async\s+(function|\(|[a-zA-Z])/)) {
+      patterns.asyncAwait.push(file);
+    }
+    if (content.match(/\.then\(/) || content.match(/\.catch\(/)) {
+      patterns.promises.push(file);
+    }
+    if (content.match(/callback\s*\(/) || content.match(/\(\s*err\s*,/)) {
+      patterns.callbacks.push(file);
+    }
+  }
+
+  const issues: PatternIssue[] = [];
+
+  // Modern codebases should prefer async/await
+  if (patterns.callbacks.length > 0 && patterns.asyncAwait.length > 0) {
+    issues.push({
+      files: [...patterns.callbacks, ...patterns.asyncAwait],
+      type: 'async-style',
+      description: 'Mixed async patterns: callbacks and async/await',
+      examples: [
+        `Callbacks found in: ${patterns.callbacks.slice(0, 3).join(', ')}`,
+        `Async/await used in: ${patterns.asyncAwait.slice(0, 3).join(', ')}`
+      ],
+      severity: 'minor'
+    });
+  }
+
+  // Mixing .then() chains with async/await
+  if (patterns.promises.length > patterns.asyncAwait.length * 0.3 && patterns.asyncAwait.length > 0) {
+    issues.push({
+      files: patterns.promises,
+      type: 'async-style',
+      description: 'Consider using async/await instead of promise chains for consistency',
+      examples: patterns.promises.slice(0, 5),
+      severity: 'info'
+    });
+  }
+
+  return issues;
+}
+
+async function analyzeImportStyles(files: string[]): Promise<PatternIssue[]> {
+  const patterns = {
+    esModules: [] as string[],
+    commonJS: [] as string[],
+    mixed: [] as string[]
+  };
+
+  for (const file of files) {
+    const content = await readFileContent(file);
+    const hasESM = content.match(/^import\s+/m);
+    const hasCJS = content.match(/require\s*\(/);
+    
+    if (hasESM && hasCJS) {
+      patterns.mixed.push(file);
+    } else if (hasESM) {
+      patterns.esModules.push(file);
+    } else if (hasCJS) {
+      patterns.commonJS.push(file);
+    }
+  }
+
+  const issues: PatternIssue[] = [];
+
+  // Check for mixed import styles in same file
+  if (patterns.mixed.length > 0) {
+    issues.push({
+      files: patterns.mixed,
+      type: 'import-style',
+      description: 'Mixed ES modules and CommonJS imports in same files',
+      examples: patterns.mixed.slice(0, 5),
+      severity: 'major'
+    });
+  }
+
+  // Check for inconsistent styles across project
+  if (patterns.esModules.length > 0 && patterns.commonJS.length > 0) {
+    const ratio = patterns.commonJS.length / (patterns.esModules.length + patterns.commonJS.length);
+    if (ratio > 0.2 && ratio < 0.8) {
+      issues.push({
+        files: [...patterns.esModules, ...patterns.commonJS],
+        type: 'import-style',
+        description: 'Inconsistent import styles across project',
+        examples: [
+          `ES modules: ${patterns.esModules.length} files`,
+          `CommonJS: ${patterns.commonJS.length} files`
+        ],
+        severity: 'minor'
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Analyzes API design consistency
+ */
+export async function analyzeAPIDesign(files: string[]): Promise<PatternIssue[]> {
+  // This would analyze:
+  // - Function parameter order consistency
+  // - Return type patterns
+  // - Options object vs individual parameters
+  // For now, return empty array
+  return [];
+}