@aiready/consistency 0.5.0 → 0.6.1

package/src/analyzers/naming-ast.ts

@@ -0,0 +1,378 @@
+import { TSESTree } from '@typescript-eslint/typescript-estree';
+import { loadConfig } from '@aiready/core';
+import { dirname } from 'path';
+import type { NamingIssue } from '../types';
+import {
+  parseFile,
+  traverseAST,
+  getFunctionName,
+  getLineNumber,
+  isCoverageContext,
+  isLoopStatement,
+  isCallback,
+} from '../utils/ast-parser';
+import { ScopeTracker } from '../utils/scope-tracker';
+import {
+  buildCodeContext,
+  adjustSeverity,
+  isAcceptableInContext,
+  calculateComplexity,
+} from '../utils/context-detector';
+
+// Common short English words that are NOT abbreviations (full, valid words)
+const COMMON_SHORT_WORDS = new Set([
+  'day', 'key', 'net', 'to', 'go', 'for', 'not', 'new', 'old', 'top', 'end',
+  'run', 'try', 'use', 'get', 'set', 'add', 'put', 'map', 'log', 'row', 'col',
+  'tab', 'box', 'div', 'nav', 'tag', 'any', 'all', 'one', 'two', 'out', 'off',
+  'on', 'yes', 'no', 'now', 'max', 'min', 'sum', 'avg', 'ref', 'src', 'dst',
+  'raw', 'def', 'sub', 'pub', 'pre', 'mid', 'alt', 'opt', 'tmp', 'ext', 'sep',
+  'and', 'from', 'how', 'pad', 'bar', 'non',
+  'tax', 'cat', 'dog', 'car', 'bus', 'web', 'app', 'war', 'law', 'pay', 'buy',
+  'win', 'cut', 'hit', 'hot', 'pop', 'job', 'age', 'act', 'let', 'lot', 'bad',
+  'big', 'far', 'few', 'own', 'per', 'red', 'low', 'see', 'six', 'ten', 'way',
+  'who', 'why', 'yet', 'via', 'due', 'fee', 'fun', 'gas', 'gay', 'god', 'gun',
+  'guy', 'ice', 'ill', 'kid', 'mad', 'man', 'mix', 'mom', 'mrs', 'nor', 'odd',
+  'oil', 'pan', 'pet', 'pit', 'pot', 'pow', 'pro', 'raw', 'rep', 'rid', 'sad',
+  'sea', 'sit', 'sky', 'son', 'tea', 'tie', 'tip', 'van', 'war', 'win', 'won'
+]);
+
+// Comprehensive list of acceptable abbreviations and acronyms
+const ACCEPTABLE_ABBREVIATIONS = new Set([
+  'id', 'uid', 'gid', 'pid', 'i', 'j', 'k', 'n', 'm',
+  'url', 'uri', 'api', 'cdn', 'dns', 'ip', 'tcp', 'udp', 'http', 'ssl', 'tls',
+  'utm', 'seo', 'rss', 'xhr', 'ajax', 'cors', 'ws', 'wss',
+  'json', 'xml', 'yaml', 'csv', 'html', 'css', 'svg', 'pdf',
+  'img', 'txt', 'doc', 'docx', 'xlsx', 'ppt', 'md', 'rst', 'jpg', 'png', 'gif',
+  'db', 'sql', 'orm', 'dao', 'dto', 'ddb', 'rds', 'nosql',
+  'fs', 'dir', 'tmp', 'src', 'dst', 'bin', 'lib', 'pkg',
+  'os', 'env', 'arg', 'cli', 'cmd', 'exe', 'cwd', 'pwd',
+  'ui', 'ux', 'gui', 'dom', 'ref',
+  'req', 'res', 'ctx', 'err', 'msg', 'auth',
+  'max', 'min', 'avg', 'sum', 'abs', 'cos', 'sin', 'tan', 'log', 'exp',
+  'pow', 'sqrt', 'std', 'var', 'int', 'num', 'idx',
+  'now', 'utc', 'tz', 'ms', 'sec', 'hr', 'min', 'yr', 'mo',
+  'app', 'cfg', 'config', 'init', 'len', 'val', 'str', 'obj', 'arr',
+  'gen', 'def', 'raw', 'new', 'old', 'pre', 'post', 'sub', 'pub',
+  'ts', 'js', 'jsx', 'tsx', 'py', 'rb', 'vue', 're', 'fn', 'fns', 'mod', 'opts', 'dev',
+  's3', 'ec2', 'sqs', 'sns', 'vpc', 'ami', 'iam', 'acl', 'elb', 'alb', 'nlb', 'aws',
+  'ses', 'gst', 'cdk', 'btn', 'buf', 'agg', 'ocr', 'ai', 'cf', 'cfn', 'ga',
+  'fcp', 'lcp', 'cls', 'ttfb', 'tti', 'fid', 'fps', 'qps', 'rps', 'tps', 'wpm',
+  'po', 'e2e', 'a11y', 'i18n', 'l10n', 'spy',
+  'sk', 'fy', 'faq', 'og', 'seo', 'cta', 'roi', 'kpi', 'ttl', 'pct',
+  'mac', 'hex', 'esm', 'git', 'rec', 'loc', 'dup',
+  'is', 'has', 'can', 'did', 'was', 'are',
+  'd', 't', 'dt',
+  's', 'b', 'f', 'l',  // Coverage metrics
+  'vid', 'pic', 'img', 'doc', 'msg'
+]);
+
+/**
+ * AST-based naming analyzer
+ */
+export async function analyzeNamingAST(files: string[]): Promise<NamingIssue[]> {
+  const issues: NamingIssue[] = [];
+
+  // Load config
+  const rootDir = files.length > 0 ? dirname(files[0]) : process.cwd();
+  const config = loadConfig(rootDir);
+  const consistencyConfig = config?.tools?.['consistency'];
+
+  // Merge custom configuration
+  const customAbbreviations = new Set(consistencyConfig?.acceptedAbbreviations || []);
+  const customShortWords = new Set(consistencyConfig?.shortWords || []);
+  const disabledChecks = new Set(consistencyConfig?.disableChecks || []);
+
+  const allAbbreviations = new Set([...ACCEPTABLE_ABBREVIATIONS, ...customAbbreviations]);
+  const allShortWords = new Set([...COMMON_SHORT_WORDS, ...customShortWords]);
+
+  for (const file of files) {
+    try {
+      const ast = parseFile(file);
+      if (!ast) continue; // Skip files that fail to parse
+
+      const fileIssues = analyzeFileNamingAST(
+        file,
+        ast,
+        allAbbreviations,
+        allShortWords,
+        disabledChecks
+      );
+      issues.push(...fileIssues);
+    } catch (error) {
+      console.warn(`Skipping ${file} due to parse error:`, error);
+    }
+  }
+
+  return issues;
+}
+
+function analyzeFileNamingAST(
+  file: string,
+  ast: TSESTree.Program,
+  allAbbreviations: Set<string>,
+  allShortWords: Set<string>,
+  disabledChecks: Set<string>
+): NamingIssue[] {
+  const issues: NamingIssue[] = [];
+  const scopeTracker = new ScopeTracker(ast);
+  const context = buildCodeContext(file, ast);
+  const ancestors: TSESTree.Node[] = [];
+
+  // First pass: Build scope tree and track all variables
+  traverseAST(ast, {
+    enter: (node, parent) => {
+      ancestors.push(node);
+
+      // Enter scopes
+      if (node.type === 'FunctionDeclaration' || node.type === 'FunctionExpression' || node.type === 'ArrowFunctionExpression') {
+        scopeTracker.enterScope('function', node);
+        
+        // Track parameters
+        if ('params' in node) {
+          for (const param of node.params) {
+            if (param.type === 'Identifier') {
+              scopeTracker.declareVariable(param.name, param, getLineNumber(param), {
+                isParameter: true,
+              });
+            } else if (param.type === 'ObjectPattern' || param.type === 'ArrayPattern') {
+              // Handle destructured parameters
+              extractIdentifiersFromPattern(param, scopeTracker, true);
+            }
+          }
+        }
+      } else if (node.type === 'BlockStatement') {
+        scopeTracker.enterScope('block', node);
+      } else if (isLoopStatement(node)) {
+        scopeTracker.enterScope('loop', node);
+      } else if (node.type === 'ClassDeclaration') {
+        scopeTracker.enterScope('class', node);
+      }
+
+      // Track variable declarations
+      if (node.type === 'VariableDeclarator') {
+        if (node.id.type === 'Identifier') {
+          const isInCoverage = isCoverageContext(node, ancestors);
+          scopeTracker.declareVariable(
+            node.id.name,
+            node.id,
+            getLineNumber(node.id),
+            {
+              type: ('typeAnnotation' in node.id) ? (node.id as any).typeAnnotation : null,
+              isDestructured: false,
+              isLoopVariable: scopeTracker.getCurrentScopeType() === 'loop',
+            }
+          );
+        } else if (node.id.type === 'ObjectPattern' || node.id.type === 'ArrayPattern') {
+          extractIdentifiersFromPattern(node.id, scopeTracker, false, ancestors);
+        }
+      }
+
+      // Track references
+      if (node.type === 'Identifier' && parent) {
+        // Only count as reference if it's not a declaration
+        if (parent.type !== 'VariableDeclarator' || parent.id !== node) {
+          if (parent.type !== 'FunctionDeclaration' || parent.id !== node) {
+            scopeTracker.addReference(node.name, node);
+          }
+        }
+      }
+    },
+    leave: (node) => {
+      ancestors.pop();
+
+      // Exit scopes
+      if (
+        node.type === 'FunctionDeclaration' ||
+        node.type === 'FunctionExpression' ||
+        node.type === 'ArrowFunctionExpression' ||
+        node.type === 'BlockStatement' ||
+        isLoopStatement(node) ||
+        node.type === 'ClassDeclaration'
+      ) {
+        scopeTracker.exitScope();
+      }
+    },
+  });
+
+  // Second pass: Analyze all variables
+  const allVariables = scopeTracker.getAllVariables();
+
+  for (const varInfo of allVariables) {
+    const name = varInfo.name;
+    const line = varInfo.declarationLine;
+
+    // Skip if checks are disabled
+    if (disabledChecks.has('single-letter') && name.length === 1) continue;
+    if (disabledChecks.has('abbreviation') && name.length <= 3) continue;
+
+    // Check coverage context
+    const isInCoverage = ['s', 'b', 'f', 'l'].includes(name) && varInfo.isDestructured;
+    if (isInCoverage) continue;
+
+    // Check if acceptable in context
+    const functionComplexity = varInfo.node.type === 'Identifier' && 'parent' in varInfo.node
+      ? calculateComplexity(varInfo.node as any)
+      : context.complexity;
+      
+    if (isAcceptableInContext(name, context, {
+      isLoopVariable: varInfo.isLoopVariable || allAbbreviations.has(name),
+      isParameter: varInfo.isParameter,
+      isDestructured: varInfo.isDestructured,
+      complexity: functionComplexity,
+    })) {
+      continue;
+    }
+
+    // Single letter check
+    if (name.length === 1 && !allAbbreviations.has(name) && !allShortWords.has(name)) {
+      // Check if short-lived
+      const isShortLived = scopeTracker.isShortLived(varInfo, 5);
+      if (!isShortLived) {
+        issues.push({
+          file,
+          line,
+          type: 'poor-naming',
+          identifier: name,
+          severity: adjustSeverity('minor', context, 'poor-naming'),
+          suggestion: `Use descriptive variable name instead of single letter '${name}'`,
+        });
+      }
+      continue;
+    }
+
+    // Abbreviation check (2-3 letters)
+    if (name.length >= 2 && name.length <= 3) {
+      if (!allShortWords.has(name.toLowerCase()) && !allAbbreviations.has(name.toLowerCase())) {
+        // Check if short-lived for abbreviations too
+        const isShortLived = scopeTracker.isShortLived(varInfo, 5);
+        if (!isShortLived) {
+          issues.push({
+            file,
+            line,
+            type: 'abbreviation',
+            identifier: name,
+            severity: adjustSeverity('info', context, 'abbreviation'),
+            suggestion: `Consider using full word instead of abbreviation '${name}'`,
+          });
+        }
+      }
+      continue;
+    }
+
+    // Snake_case check for TypeScript/JavaScript
+    if (!disabledChecks.has('convention-mix') && file.match(/\.(ts|tsx|js|jsx)$/)) {
+      if (name.includes('_') && !name.startsWith('_') && name.toLowerCase() === name) {
+        const camelCase = name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+        issues.push({
+          file,
+          line,
+          type: 'convention-mix',
+          identifier: name,
+          severity: adjustSeverity('minor', context, 'convention-mix'),
+          suggestion: `Use camelCase '${camelCase}' instead of snake_case in TypeScript/JavaScript`,
+        });
+      }
+    }
+  }
+
+  // Third pass: Analyze function names
+  if (!disabledChecks.has('unclear')) {
+    traverseAST(ast, {
+      enter: (node) => {
+        if (node.type === 'FunctionDeclaration' || node.type === 'MethodDefinition') {
+          const name = getFunctionName(node);
+          if (!name) return;
+
+          const line = getLineNumber(node);
+
+          // Skip entry points
+          if (['main', 'init', 'setup', 'bootstrap'].includes(name)) return;
+
+          // Check for action verbs and patterns
+          const hasActionVerb = name.match(/^(get|set|is|has|can|should|create|update|delete|fetch|load|save|process|handle|validate|check|find|search|filter|map|reduce|make|do|run|start|stop|build|parse|format|render|calculate|compute|generate|transform|convert|normalize|sanitize|encode|decode|compress|extract|merge|split|join|sort|compare|test|verify|ensure|apply|execute|invoke|call|emit|dispatch|trigger|listen|subscribe|unsubscribe|add|remove|clear|reset|toggle|enable|disable|open|close|connect|disconnect|send|receive|read|write|import|export|register|unregister|mount|unmount|track|store|persist|upsert|derive|classify|combine|discover|activate|require|assert|expect|mask|escape|sign|put|list|complete|page|safe|mock|pick|pluralize|text|count|detect|select)/);
+          
+          const isFactoryPattern = name.match(/(Factory|Builder|Creator|Generator|Provider|Adapter|Mock)$/);
+          const isEventHandler = name.match(/^on[A-Z]/);
+          const isDescriptiveLong = name.length > 15;
+          const isReactHook = name.match(/^use[A-Z]/);
+          const isHelperPattern = name.match(/^(to|from|with|without|for|as|into)\w+/) || 
+                                  name.match(/^\w+(To|From|With|Without|For|As|Into)\w*$/); // xForY, xToY patterns
+          const isUtilityName = ['cn', 'proxy', 'sitemap', 'robots', 'gtag'].includes(name);
+          const isLanguageKeyword = ['constructor', 'toString', 'valueOf', 'toJSON'].includes(name);
+          const isFrameworkPattern = name.match(/^(goto|fill|click|select|submit|wait|expect)\w*/); // Page Object Model, test framework patterns
+          
+          // Descriptive patterns: countX, totalX, etc.
+          const isDescriptivePattern = name.match(/^(default|total|count|sum|avg|max|min|initial|current|previous|next)\w+/) ||
+                                       name.match(/\w+(Count|Total|Sum|Average|List|Map|Set|Config|Settings|Options|Props|Data|Info|Details|State|Status|Response|Result)$/);
+          
+          // Count capital letters for compound detection
+          const capitalCount = (name.match(/[A-Z]/g) || []).length;
+          const isCompoundWord = capitalCount >= 3; // daysSinceLastCommit has 4 capitals
+
+          if (!hasActionVerb && !isFactoryPattern && !isEventHandler && !isDescriptiveLong && !isReactHook && !isHelperPattern && !isUtilityName && !isDescriptivePattern && !isCompoundWord && !isLanguageKeyword && !isFrameworkPattern) {
+            issues.push({
+              file,
+              line,
+              type: 'unclear',
+              identifier: name,
+              severity: adjustSeverity('info', context, 'unclear'),
+              suggestion: `Function '${name}' should start with an action verb (get, set, create, etc.)`,
+            });
+          }
+        }
+      },
+    });
+  }
+
+  return issues;
+}
+
+/**
+ * Extract all identifiers from a destructuring pattern
+ */
+function extractIdentifiersFromPattern(
+  pattern: TSESTree.ObjectPattern | TSESTree.ArrayPattern,
+  scopeTracker: ScopeTracker,
+  isParameter: boolean,
+  ancestors?: TSESTree.Node[]
+): void {
+  if (pattern.type === 'ObjectPattern') {
+    for (const prop of pattern.properties) {
+      if (prop.type === 'Property' && prop.value.type === 'Identifier') {
+        scopeTracker.declareVariable(
+          prop.value.name,
+          prop.value,
+          getLineNumber(prop.value),
+          {
+            isParameter,
+            isDestructured: true,
+          }
+        );
+      } else if (prop.type === 'RestElement' && prop.argument.type === 'Identifier') {
+        scopeTracker.declareVariable(
+          prop.argument.name,
+          prop.argument,
+          getLineNumber(prop.argument),
+          {
+            isParameter,
+            isDestructured: true,
+          }
+        );
+      }
+    }
+  } else if (pattern.type === 'ArrayPattern') {
+    for (const element of pattern.elements) {
+      if (element && element.type === 'Identifier') {
+        scopeTracker.declareVariable(
+          element.name,
+          element,
+          getLineNumber(element),
+          {
+            isParameter,
+            isDestructured: true,
+          }
+        );
+      }
+    }
+  }
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export { analyzeConsistency } from './analyzer';
-export { analyzeNaming, detectNamingConventions } from './analyzers/naming';
+export { analyzeNamingAST } from './analyzers/naming-ast';
+export { analyzeNaming, detectNamingConventions } from './analyzers/naming'; // Legacy regex version
 export { analyzePatterns } from './analyzers/patterns';
 export type {
   ConsistencyOptions,

package/src/utils/ast-parser.ts

@@ -0,0 +1,181 @@
+import { parse, TSESTree } from '@typescript-eslint/typescript-estree';
+import { readFileSync } from 'fs';
+
+/**
+ * Parse a file into an AST
+ */
+export function parseFile(filePath: string, content?: string): TSESTree.Program | null {
+  try {
+    const code = content ?? readFileSync(filePath, 'utf-8');
+    const isTypeScript = filePath.match(/\.tsx?$/);
+    
+    return parse(code, {
+      jsx: filePath.match(/\.[jt]sx$/i) !== null,
+      loc: true,
+      range: true,
+      comment: false,
+      tokens: false,
+      // Relaxed parsing for JavaScript files
+      sourceType: 'module',
+      ecmaVersion: 'latest',
+      // Only use TypeScript parser features for .ts/.tsx files
+      filePath: isTypeScript ? filePath : undefined,
+    });
+  } catch (error) {
+    // If TypeScript parsing fails, return null (file might have syntax errors)
+    console.warn(`Failed to parse ${filePath}:`, error instanceof Error ? error.message : error);
+    return null;
+  }
+}
+
+/**
+ * Traverse AST nodes with a visitor pattern
+ */
+export function traverseAST(
+  node: TSESTree.Node,
+  visitor: {
+    enter?: (node: TSESTree.Node, parent: TSESTree.Node | null) => void;
+    leave?: (node: TSESTree.Node, parent: TSESTree.Node | null) => void;
+  },
+  parent: TSESTree.Node | null = null
+): void {
+  if (!node) return;
+
+  visitor.enter?.(node, parent);
+
+  // Visit children
+  for (const key of Object.keys(node)) {
+    const value = (node as any)[key];
+    
+    if (Array.isArray(value)) {
+      for (const child of value) {
+        if (child && typeof child === 'object' && 'type' in child) {
+          traverseAST(child as TSESTree.Node, visitor, node);
+        }
+      }
+    } else if (value && typeof value === 'object' && 'type' in value) {
+      traverseAST(value as TSESTree.Node, visitor, node);
+    }
+  }
+
+  visitor.leave?.(node, parent);
+}
+
+/**
+ * Check if a node is within a specific type of ancestor
+ */
+export function hasAncestor(
+  node: TSESTree.Node,
+  ancestorTypes: string[],
+  ancestors: TSESTree.Node[]
+): boolean {
+  return ancestors.some(ancestor => ancestorTypes.includes(ancestor.type));
+}
+
+/**
+ * Get the name of an identifier or pattern
+ */
+export function getIdentifierName(node: TSESTree.Node): string | null {
+  if (node.type === 'Identifier') {
+    return node.name;
+  }
+  return null;
+}
+
+/**
+ * Check if a node is a loop
+ */
+export function isLoopStatement(node: TSESTree.Node): boolean {
+  return [
+    'ForStatement',
+    'ForInStatement',
+    'ForOfStatement',
+    'WhileStatement',
+    'DoWhileStatement',
+  ].includes(node.type);
+}
+
+/**
+ * Check if a node is an arrow function or callback
+ */
+export function isCallback(node: TSESTree.Node): boolean {
+  if (node.type === 'ArrowFunctionExpression') {
+    return true;
+  }
+  if (node.type === 'FunctionExpression') {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Extract function/method name from various declaration types
+ */
+export function getFunctionName(node: TSESTree.Node): string | null {
+  switch (node.type) {
+    case 'FunctionDeclaration':
+      return node.id?.name ?? null;
+    case 'FunctionExpression':
+      return node.id?.name ?? null;
+    case 'ArrowFunctionExpression':
+      return null; // Arrow functions don't have names directly
+    case 'MethodDefinition':
+      if (node.key.type === 'Identifier') {
+        return node.key.name;
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Check if a variable declaration is in a destructuring pattern
+ */
+export function isInDestructuring(node: TSESTree.Node): boolean {
+  if (!node) return false;
+  
+  return node.type === 'ObjectPattern' || node.type === 'ArrayPattern';
+}
+
+/**
+ * Get the line number from a node
+ */
+export function getLineNumber(node: TSESTree.Node): number {
+  return node.loc?.start.line ?? 0;
+}
+
+/**
+ * Check if a node represents a coverage metric context
+ */
+export function isCoverageContext(node: TSESTree.Node, ancestors: TSESTree.Node[]): boolean {
+  // Check if any ancestor or the node itself references coverage-related properties
+  const coveragePatterns = /coverage|summary|metrics|pct|percent|statements|branches|functions|lines/i;
+  
+  // Check variable name
+  if (node.type === 'Identifier' && coveragePatterns.test(node.name)) {
+    return true;
+  }
+  
+  // Check if it's a property of something coverage-related
+  for (const ancestor of ancestors.slice(-3)) { // Check last 3 ancestors
+    if (ancestor.type === 'MemberExpression') {
+      const memberExpr = ancestor as TSESTree.MemberExpression;
+      if (memberExpr.object.type === 'Identifier' && coveragePatterns.test(memberExpr.object.name)) {
+        return true;
+      }
+    }
+    if (ancestor.type === 'ObjectPattern' || ancestor.type === 'ObjectExpression') {
+      // Check if parent variable has coverage-related name
+      const parent = ancestors[ancestors.indexOf(ancestor) - 1];
+      if (parent?.type === 'VariableDeclarator') {
+        const varDecl = parent as TSESTree.VariableDeclarator;
+        if (varDecl.id.type === 'Identifier' && coveragePatterns.test(varDecl.id.name)) {
+          return true;
+        }
+      }
+    }
+  }
+  
+  return false;
+}