@aiready/consistency 0.3.0 → 0.3.4

package/README.md

@@ -25,17 +25,24 @@ aiready-consistency ./src
 Inconsistent code patterns confuse AI models and reduce their effectiveness. This tool analyzes:
 
 ### 🏷️ Naming Quality & Conventions
-- Single-letter variables (except loop counters)
-- Unclear abbreviations
-- Mixed naming conventions (camelCase vs snake_case)
-- Boolean naming (should use is/has/can prefixes)
-- Function naming (should start with action verbs)
+- **Single-letter variables** - Detects unclear variable names (skips common iterators: i, j, k, l, x, y, z in appropriate contexts)
+- **Abbreviations** - Identifies unclear abbreviations while allowing 60+ standard ones (env, req, res, ctx, max, min, etc.)
+- **Mixed naming conventions** - Detects snake_case in TypeScript/JavaScript projects (should use camelCase)
+- **Boolean naming** - Ensures booleans use clear prefixes (is/has/can/should)
+- **Function naming** - Checks for action verbs while allowing factory patterns and descriptive names
+
+**Smart Detection:** The tool understands context and won't flag:
+- Common abbreviations (env, api, url, max, min, now, etc.)
+- Boolean prefixes (is, has, can used as variables)
+- Loop iterators in appropriate contexts
+- Factory/builder patterns
+- Long descriptive function names
 
 ### 🔄 Pattern Consistency
-- Error handling strategies (try-catch vs returns)
-- Async patterns (async/await vs promises vs callbacks)
-- Import styles (ES modules vs CommonJS)
-- API design patterns
+- **Error handling strategies** - Detects mixed approaches (try-catch vs returns vs throws)
+- **Async patterns** - Identifies mixing of async/await, promises, and callbacks
+- **Import styles** - Flags mixing of ES modules and CommonJS
+- **API design patterns** - Ensures consistent patterns across endpoints
 
 ### 🏗️ Architectural Consistency *(coming soon)*
 - File organization patterns
@@ -149,6 +156,20 @@ Create `aiready.json` in your project root:
 | `checkPatterns` | boolean | `true` | Check code pattern consistency |
 | `minSeverity` | string | `'info'` | Filter: `'info'`, `'minor'`, `'major'`, `'critical'` |
 
+### Acceptable Abbreviations
+
+The tool recognizes 60+ standard abbreviations and won't flag them:
+
+**Web/Network:** url, uri, api, cdn, dns, ip, http, utm, seo, xhr  
+**Data:** json, xml, yaml, csv, html, css, svg, pdf, dto, dao  
+**System:** env, os, fs, cli, tmp, src, dst, bin, lib, pkg  
+**Request/Response:** req, res, ctx, err, msg  
+**Math:** max, min, avg, sum, abs, cos, sin, log, sqrt  
+**Time:** now, utc, ms, sec  
+**Common:** id, uid, db, sql, orm, ui, ux, dom, ref, val, str, obj, arr, cfg, init
+
+See [naming.ts](src/analyzers/naming.ts) for the complete list.
+
 ## 🔧 Programmatic API
 
 ```typescript

package/dist/chunk-LUAREV6A.mjs

@@ -0,0 +1,508 @@
+// src/analyzers/naming.ts
+import { readFileContent } from "@aiready/core";
+var ACCEPTABLE_ABBREVIATIONS = /* @__PURE__ */ new Set([
+  // Standard identifiers
+  "id",
+  "uid",
+  "gid",
+  "pid",
+  // Web/Network
+  "url",
+  "uri",
+  "api",
+  "cdn",
+  "dns",
+  "ip",
+  "tcp",
+  "udp",
+  "http",
+  "ssl",
+  "tls",
+  "utm",
+  "seo",
+  "rss",
+  "xhr",
+  "ajax",
+  // Data formats
+  "json",
+  "xml",
+  "yaml",
+  "csv",
+  "html",
+  "css",
+  "svg",
+  "pdf",
+  // Databases
+  "db",
+  "sql",
+  "orm",
+  "dao",
+  "dto",
+  // File system
+  "fs",
+  "dir",
+  "tmp",
+  "src",
+  "dst",
+  "bin",
+  "lib",
+  "pkg",
+  // Operating system
+  "os",
+  "env",
+  "arg",
+  "cli",
+  "cmd",
+  "exe",
+  // UI/UX
+  "ui",
+  "ux",
+  "gui",
+  "dom",
+  "ref",
+  // Request/Response
+  "req",
+  "res",
+  "ctx",
+  "err",
+  "msg",
+  // Mathematics/Computing
+  "max",
+  "min",
+  "avg",
+  "sum",
+  "abs",
+  "cos",
+  "sin",
+  "tan",
+  "log",
+  "exp",
+  "pow",
+  "sqrt",
+  "std",
+  "var",
+  "int",
+  "num",
+  // Time
+  "now",
+  "utc",
+  "tz",
+  "ms",
+  "sec",
+  // Common patterns
+  "app",
+  "cfg",
+  "config",
+  "init",
+  "len",
+  "val",
+  "str",
+  "obj",
+  "arr",
+  "gen",
+  "def",
+  "raw",
+  "new",
+  "old",
+  "pre",
+  "post",
+  "sub",
+  "pub",
+  // Boolean helpers (these are intentional short names)
+  "is",
+  "has",
+  "can",
+  "did",
+  "was",
+  "are"
+]);
+async function analyzeNaming(files) {
+  const issues = [];
+  for (const file of files) {
+    const content = await readFileContent(file);
+    const fileIssues = analyzeFileNaming(file, content);
+    issues.push(...fileIssues);
+  }
+  return issues;
+}
+function analyzeFileNaming(file, content) {
+  const issues = [];
+  const lines = content.split("\n");
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+    const singleLetterMatches = line.matchAll(/\b(?:const|let|var)\s+([a-hm-z])\s*=/gi);
+    for (const match of singleLetterMatches) {
+      const letter = match[1].toLowerCase();
+      const isInLoopContext = line.includes("for") || line.includes(".map") || line.includes(".filter") || line.includes(".forEach") || line.includes(".reduce");
+      if (!isInLoopContext && !["x", "y", "z", "i", "j", "k", "l", "n", "m"].includes(letter)) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: "poor-naming",
+          identifier: match[1],
+          severity: "minor",
+          suggestion: `Use descriptive variable name instead of single letter '${match[1]}'`
+        });
+      }
+    }
+    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].toLowerCase();
+      if (!ACCEPTABLE_ABBREVIATIONS.has(abbrev)) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: "abbreviation",
+          identifier: match[1],
+          severity: "info",
+          suggestion: `Consider using full word instead of abbreviation '${match[1]}'`
+        });
+      }
+    }
+    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`
+        });
+      }
+    }
+    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`
+        });
+      }
+    }
+    const functionMatches = line.matchAll(/function\s+([a-z][a-zA-Z0-9]*)/g);
+    for (const match of functionMatches) {
+      const name = match[1];
+      const isFactoryPattern = name.match(/(Factory|Builder|Creator|Generator)$/);
+      const isEventHandler = name.match(/^on[A-Z]/);
+      const isDescriptiveLong = name.length > 20;
+      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)/);
+      if (!hasActionVerb && !isFactoryPattern && !isEventHandler && !isDescriptiveLong) {
+        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) {
+  return str.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+function detectNamingConventions(files, allIssues) {
+  const camelCaseCount = allIssues.filter((i) => i.type === "convention-mix").length;
+  const totalChecks = files.length * 10;
+  if (camelCaseCount / totalChecks > 0.3) {
+    return { dominantConvention: "mixed", conventionScore: 0.5 };
+  }
+  return { dominantConvention: "camelCase", conventionScore: 0.9 };
+}
+
+// src/analyzers/patterns.ts
+import { readFileContent as readFileContent2 } from "@aiready/core";
+async function analyzePatterns(files) {
+  const issues = [];
+  const errorHandlingIssues = await analyzeErrorHandling(files);
+  issues.push(...errorHandlingIssues);
+  const asyncIssues = await analyzeAsyncPatterns(files);
+  issues.push(...asyncIssues);
+  const importIssues = await analyzeImportStyles(files);
+  issues.push(...importIssues);
+  return issues;
+}
+async function analyzeErrorHandling(files) {
+  const patterns = {
+    tryCatch: [],
+    throwsError: [],
+    returnsNull: [],
+    returnsError: []
+  };
+  for (const file of files) {
+    const content = await readFileContent2(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 = [];
+  const strategiesUsed = Object.values(patterns).filter((p) => p.length > 0).length;
+  if (strategiesUsed > 2) {
+    issues.push({
+      files: [.../* @__PURE__ */ 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) {
+  const patterns = {
+    asyncAwait: [],
+    promises: [],
+    callbacks: []
+  };
+  for (const file of files) {
+    const content = await readFileContent2(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 = [];
+  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"
+    });
+  }
+  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) {
+  const patterns = {
+    esModules: [],
+    commonJS: [],
+    mixed: []
+  };
+  for (const file of files) {
+    const content = await readFileContent2(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 = [];
+  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"
+    });
+  }
+  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;
+}
+
+// src/analyzer.ts
+import { scanFiles } from "@aiready/core";
+async function analyzeConsistency(options) {
+  const {
+    checkNaming = true,
+    checkPatterns = true,
+    checkArchitecture = false,
+    // Not implemented yet
+    minSeverity = "info",
+    ...scanOptions
+  } = options;
+  const filePaths = await scanFiles(scanOptions);
+  const namingIssues = checkNaming ? await analyzeNaming(filePaths) : [];
+  const patternIssues = checkPatterns ? await analyzePatterns(filePaths) : [];
+  const results = [];
+  const fileIssuesMap = /* @__PURE__ */ new Map();
+  for (const issue of namingIssues) {
+    if (!shouldIncludeSeverity(issue.severity, minSeverity)) {
+      continue;
+    }
+    const 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);
+  }
+  for (const issue of patternIssues) {
+    if (!shouldIncludeSeverity(issue.severity, minSeverity)) {
+      continue;
+    }
+    const 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`
+    };
+    const firstFile = issue.files[0];
+    if (firstFile && !fileIssuesMap.has(firstFile)) {
+      fileIssuesMap.set(firstFile, []);
+    }
+    if (firstFile) {
+      fileIssuesMap.get(firstFile).push(consistencyIssue);
+    }
+  }
+  for (const [fileName, issues] of fileIssuesMap) {
+    results.push({
+      fileName,
+      issues,
+      metrics: {
+        consistencyScore: calculateConsistencyScore(issues)
+      }
+    });
+  }
+  const recommendations = generateRecommendations(namingIssues, patternIssues);
+  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, minSeverity) {
+  const severityLevels = { info: 0, minor: 1, major: 2, critical: 3 };
+  return severityLevels[severity] >= severityLevels[minSeverity];
+}
+function calculateConsistencyScore(issues) {
+  const weights = { critical: 10, major: 5, minor: 2, info: 1 };
+  const totalWeight = issues.reduce((sum, issue) => sum + weights[issue.severity], 0);
+  return Math.max(0, 1 - totalWeight / 100);
+}
+function generateRecommendations(namingIssues, patternIssues) {
+  const recommendations = [];
+  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;
+}
+
+export {
+  analyzeNaming,
+  detectNamingConventions,
+  analyzePatterns,
+  analyzeConsistency
+};