@aiready/consistency 0.3.0 → 0.3.3

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/consistency@0.3.0 build /Users/pengcao/projects/aiready/packages/consistency
+> @aiready/consistency@0.3.3 build /Users/pengcao/projects/aiready/packages/consistency
 > tsup src/index.ts src/cli.ts --format cjs,esm --dts
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -9,15 +9,15 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-CJS dist/index.js 14.13 KB
-CJS dist/cli.js   23.02 KB
-CJS ⚡️ Build success in 57ms
-ESM dist/index.mjs          220.00 B
+CJS dist/cli.js   25.23 KB
+CJS dist/index.js 16.34 KB
+CJS ⚡️ Build success in 79ms
+ESM dist/chunk-LUAREV6A.mjs 15.11 KB
 ESM dist/cli.mjs            8.54 KB
-ESM dist/chunk-CF4LU7KE.mjs 12.90 KB
-ESM ⚡️ Build success in 57ms
+ESM dist/index.mjs          220.00 B
+ESM ⚡️ Build success in 79ms
 DTS Build start
-DTS ⚡️ Build success in 558ms
+DTS ⚡️ Build success in 587ms
 DTS dist/cli.d.ts    20.00 B
 DTS dist/index.d.ts  2.60 KB
 DTS dist/cli.d.mts   20.00 B

package/.turbo/turbo-test.log

@@ -1,17 +1,17 @@
 
 
-> @aiready/consistency@0.3.0 test /Users/pengcao/projects/aiready/packages/consistency
+> @aiready/consistency@0.3.3 test /Users/pengcao/projects/aiready/packages/consistency
 > vitest run
 
 
  RUN  v2.1.9 /Users/pengcao/projects/aiready/packages/consistency
 
-[?25l ❯ src/__tests__/analyzer.test.ts (14)
-   ❯ analyzeConsistency (2)
+[?25l   ❯ analyzeConsistency (2)
      ⠙ should analyze naming issues
      · should detect minimum severity filtering
-   · analyzeNaming (4)
+   · analyzeNaming (5)
      · should detect single letter variables
+     · should NOT flag acceptable abbreviations
      · should detect snake_case in TypeScript files
      · should detect unclear boolean names
      · should allow common abbreviations
@@ -26,12 +26,33 @@
      · should generate relevant recommendations
      · should suggest standardizing error handling
      · should suggest using async/await consistently
- ✓ src/__tests__/analyzer.test.ts (14)
+[?25l   ✓ analyzeConsistency (2)
+     ✓ should analyze naming issues
+     ✓ should detect minimum severity filtering
+   ✓ analyzeNaming (5)
+     ✓ should detect single letter variables
+     ✓ should NOT flag acceptable abbreviations
+     ✓ should detect snake_case in TypeScript files
+     ✓ should detect unclear boolean names
+     ✓ should allow common abbreviations
+   ✓ analyzePatterns (3)
+     ✓ should detect mixed error handling
+     ✓ should detect mixed async patterns
+     ✓ should detect mixed import styles
+   ✓ consistency scoring (2)
+     ✓ should calculate consistency score correctly
+     ✓ should weight critical issues more than info
+   ✓ recommendations (3)
+     ✓ should generate relevant recommendations
+     ✓ should suggest standardizing error handling
+     ✓ should suggest using async/await consistently
+ ✓ src/__tests__/analyzer.test.ts (15)
    ✓ analyzeConsistency (2)
      ✓ should analyze naming issues
      ✓ should detect minimum severity filtering
-   ✓ analyzeNaming (4)
+   ✓ analyzeNaming (5)
      ✓ should detect single letter variables
+     ✓ should NOT flag acceptable abbreviations
      ✓ should detect snake_case in TypeScript files
      ✓ should detect unclear boolean names
      ✓ should allow common abbreviations
@@ -48,8 +69,8 @@
      ✓ should suggest using async/await consistently
 
  Test Files  1 passed (1)
-      Tests  14 passed (14)
-   Start at  07:46:28
-   Duration  441ms (transform 95ms, setup 0ms, collect 166ms, tests 25ms, environment 0ms, prepare 49ms)
+      Tests  15 passed (15)
+   Start at  15:32:25
+   Duration  519ms (transform 74ms, setup 0ms, collect 251ms, tests 24ms, environment 0ms, prepare 54ms)
 
 [?25h[?25h

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
+};

package/dist/cli.js

@@ -31,6 +31,122 @@ var import_core3 = require("@aiready/core");
 
 // src/analyzers/naming.ts
 var import_core = require("@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) {
@@ -47,26 +163,30 @@ function analyzeFileNaming(file, content) {
     const lineNumber = index + 1;
     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]}'`
-      });
+      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];
-      if (!["id", "url", "api", "db", "fs", "os", "ui"].includes(abbrev.toLowerCase())) {
+      const abbrev = match[1].toLowerCase();
+      if (!ACCEPTABLE_ABBREVIATIONS.has(abbrev)) {
         issues.push({
           file,
           line: lineNumber,
           type: "abbreviation",
-          identifier: abbrev,
+          identifier: match[1],
           severity: "info",
-          suggestion: `Consider using full word instead of abbreviation '${abbrev}'`
+          suggestion: `Consider using full word instead of abbreviation '${match[1]}'`
         });
       }
     }
@@ -101,7 +221,11 @@ function analyzeFileNaming(file, content) {
     const functionMatches = line.matchAll(/function\s+([a-z][a-zA-Z0-9]*)/g);
     for (const match of functionMatches) {
       const name = match[1];
-      if (!name.match(/^(get|set|is|has|can|should|create|update|delete|fetch|load|save|process|handle|validate|check|find|search|filter|map|reduce)/)) {
+      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,

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   analyzeConsistency
-} from "./chunk-CF4LU7KE.mjs";
+} from "./chunk-LUAREV6A.mjs";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.js

@@ -32,6 +32,122 @@ var import_core3 = require("@aiready/core");
 
 // src/analyzers/naming.ts
 var import_core = require("@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) {
@@ -48,26 +164,30 @@ function analyzeFileNaming(file, content) {
     const lineNumber = index + 1;
     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]}'`
-      });
+      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];
-      if (!["id", "url", "api", "db", "fs", "os", "ui"].includes(abbrev.toLowerCase())) {
+      const abbrev = match[1].toLowerCase();
+      if (!ACCEPTABLE_ABBREVIATIONS.has(abbrev)) {
         issues.push({
           file,
           line: lineNumber,
           type: "abbreviation",
-          identifier: abbrev,
+          identifier: match[1],
           severity: "info",
-          suggestion: `Consider using full word instead of abbreviation '${abbrev}'`
+          suggestion: `Consider using full word instead of abbreviation '${match[1]}'`
         });
       }
     }
@@ -102,7 +222,11 @@ function analyzeFileNaming(file, content) {
     const functionMatches = line.matchAll(/function\s+([a-z][a-zA-Z0-9]*)/g);
     for (const match of functionMatches) {
       const name = match[1];
-      if (!name.match(/^(get|set|is|has|can|should|create|update|delete|fetch|load|save|process|handle|validate|check|find|search|filter|map|reduce)/)) {
+      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,

package/dist/index.mjs

@@ -3,7 +3,7 @@ import {
   analyzeNaming,
   analyzePatterns,
   detectNamingConventions
-} from "./chunk-CF4LU7KE.mjs";
+} from "./chunk-LUAREV6A.mjs";
 export {
   analyzeConsistency,
   analyzeNaming,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/consistency",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Detects consistency issues in naming, patterns, and architecture that confuse AI models",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -41,7 +41,7 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
-    "@aiready/core": "0.5.6"
+    "@aiready/core": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",

package/src/__tests__/analyzer.test.ts

@@ -44,6 +44,17 @@ const result = x + y;
     expect(true).toBe(true);
   });
 
+  it('should NOT flag acceptable abbreviations', () => {
+    // These should all be acceptable and NOT flagged
+    const acceptableAbbreviations = [
+      'env', 'req', 'res', 'ctx', 'err', 'api', 'url', 'id',
+      'max', 'min', 'now', 'utm', 'has', 'is', 'can',
+      'db', 'fs', 'os', 'ui', 'tmp', 'src', 'dst'
+    ];
+    // These abbreviations should not trigger warnings
+    expect(acceptableAbbreviations.length).toBeGreaterThan(0);
+  });
+
   it('should detect snake_case in TypeScript files', () => {
     const testCode = `
 const user_name = 'John';

package/src/analyzers/naming.ts

@@ -1,6 +1,37 @@
 import { readFileContent } from '@aiready/core';
 import type { NamingIssue } from '../types';
 
+// Comprehensive list of acceptable abbreviations and acronyms
+const ACCEPTABLE_ABBREVIATIONS = 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'
+]);
+
 /**
  * Analyzes naming conventions and quality
  */
@@ -26,32 +57,39 @@ function analyzeFileNaming(file: string, content: string): NamingIssue[] {
   lines.forEach((line, index) => {
     const lineNumber = index + 1;
 
-    // Check for single letter variables (except i, j, k in loops)
+    // Check for single letter variables (except i, j, k, l in loops/common contexts)
     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]}'`
-      });
+      const letter = match[1].toLowerCase();
+      // Skip if it's in a loop context or common iterator
+      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]}'`
+        });
+      }
     }
 
     // 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())) {
+      const abbrev = match[1].toLowerCase();
+      // Skip acceptable abbreviations
+      if (!ACCEPTABLE_ABBREVIATIONS.has(abbrev)) {
         issues.push({
           file,
           line: lineNumber,
           type: 'abbreviation',
-          identifier: abbrev,
+          identifier: match[1],
           severity: 'info',
-          suggestion: `Consider using full word instead of abbreviation '${abbrev}'`
+          suggestion: `Consider using full word instead of abbreviation '${match[1]}'`
         });
       }
     }
@@ -93,8 +131,16 @@ function analyzeFileNaming(file: string, content: string): NamingIssue[] {
     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)/)) {
+      // Functions should typically start with verbs, but allow:
+      // 1. Factory/builder patterns (ends with Factory, Builder, etc.)
+      // 2. Descriptive compound names that explain what they return
+      // 3. Event handlers (onClick, onSubmit, etc.)
+      const isFactoryPattern = name.match(/(Factory|Builder|Creator|Generator)$/);
+      const isEventHandler = name.match(/^on[A-Z]/);
+      const isDescriptiveLong = name.length > 20; // Long names are usually descriptive enough
+      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,