@aiready/consistency 0.20.5 → 0.20.7

package/dist/cli.js

@@ -413,7 +413,36 @@ function isCommonAbbreviation(name) {
     "ux",
     "api",
     "env",
-    "url"
+    "url",
+    "req",
+    "res",
+    "err",
+    "ctx",
+    "cb",
+    "idx",
+    "src",
+    "dir",
+    "app",
+    "dev",
+    "qa",
+    "dto",
+    "dao",
+    "ref",
+    "ast",
+    "dom",
+    "log",
+    "msg",
+    "pkg",
+    "req",
+    "err",
+    "res",
+    "css",
+    "html",
+    "xml",
+    "jsx",
+    "tsx",
+    "ts",
+    "js"
   ];
   return common.includes(name.toLowerCase());
 }
@@ -463,6 +492,44 @@ function extractDestructuredIdentifiers(node, isParameter, scopeTracker) {
 // src/analyzers/naming-generalized.ts
 var import_core3 = require("@aiready/core");
 var import_fs2 = require("fs");
+var COMMON_ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "id",
+  "db",
+  "fs",
+  "os",
+  "ip",
+  "ui",
+  "ux",
+  "api",
+  "env",
+  "url",
+  "req",
+  "res",
+  "err",
+  "ctx",
+  "cb",
+  "idx",
+  "src",
+  "dir",
+  "app",
+  "dev",
+  "qa",
+  "dto",
+  "dao",
+  "ref",
+  "ast",
+  "dom",
+  "log",
+  "msg",
+  "pkg",
+  "css",
+  "html",
+  "xml",
+  "jsx",
+  "tsx",
+  "ts",
+  "js"
+]);
 async function analyzeNamingGeneralized(files) {
   const issues = [];
   for (const file of files) {
@@ -470,10 +537,15 @@ async function analyzeNamingGeneralized(files) {
     if (!parser) continue;
     try {
       const code = (0, import_fs2.readFileSync)(file, "utf-8");
+      if (!code.trim()) continue;
       await parser.initialize();
       const result = parser.parse(code, file);
       const conventions = parser.getNamingConventions();
+      const exceptions = new Set(conventions.exceptions || []);
       for (const exp of result.exports) {
+        if (!exp.name || exp.name === "default") continue;
+        if (exceptions.has(exp.name)) continue;
+        if (COMMON_ABBREVIATIONS.has(exp.name.toLowerCase())) continue;
         let pattern;
         if (exp.type === "class") {
           pattern = conventions.classPattern;
@@ -484,7 +556,7 @@ async function analyzeNamingGeneralized(files) {
         } else if (exp.type === "function") {
           pattern = conventions.functionPattern;
         } else if (exp.type === "const") {
-          pattern = conventions.constantPattern;
+          pattern = exp.isPrimitive ? conventions.constantPattern : conventions.variablePattern;
         } else {
           pattern = conventions.variablePattern;
         }
@@ -495,7 +567,8 @@ async function analyzeNamingGeneralized(files) {
             file,
             line: exp.loc?.start.line || 1,
             column: exp.loc?.start.column || 0,
-            severity: import_core3.Severity.Major,
+            // Recalibrate naming issues to Minor to differentiate from structural/architectural issues
+            severity: import_core3.Severity.Minor,
             category: "naming",
             suggestion: `Follow ${parser.language} ${exp.type} naming convention: ${pattern.toString()}`
           });
@@ -503,7 +576,9 @@ async function analyzeNamingGeneralized(files) {
       }
       for (const imp of result.imports) {
         for (const spec of imp.specifiers) {
-          if (spec === "*" || spec === "default") continue;
+          if (!spec || spec === "*" || spec === "default") continue;
+          if (exceptions.has(spec)) continue;
+          if (COMMON_ABBREVIATIONS.has(spec.toLowerCase())) continue;
           if (!conventions.variablePattern.test(spec) && !conventions.classPattern.test(spec)) {
             issues.push({
               type: "naming-inconsistency",
@@ -511,7 +586,8 @@ async function analyzeNamingGeneralized(files) {
               file,
               line: imp.loc?.start.line || 1,
               column: imp.loc?.start.column || 0,
-              severity: import_core3.Severity.Minor,
+              severity: import_core3.Severity.Info,
+              // Reduced from Minor to Info for imports
               category: "naming",
               suggestion: `Imported identifier '${spec}' may not follow standard conventions for this language.`
             });
@@ -519,7 +595,10 @@ async function analyzeNamingGeneralized(files) {
         }
       }
     } catch (error) {
-      console.warn(`Consistency: Failed to analyze ${file}: ${error}`);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.debug(
+        `Consistency: Skipping unparseable file ${file}: ${errorMessage.split("\\n")[0]}`
+      );
     }
   }
   return issues;

package/dist/cli.mjs

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

package/dist/index.d.mts

@@ -61,8 +61,12 @@ interface ConsistencyReport {
 }
 
 /**
- * Main consistency analyzer that orchestrates all analysis types
- * Supports: TypeScript, JavaScript, Python, Java, C#, Go
+ * Main consistency analyzer that orchestrates all analysis types.
+ * Supports: TypeScript, JavaScript, Python, Java, C#, Go.
+ *
+ * @param options - Configuration for consistency analysis and file scanning.
+ * @returns Promise resolving to the comprehensive consistency report.
+ * @lastUpdated 2026-03-18
  */
 declare function analyzeConsistency(options: ConsistencyOptions): Promise<ConsistencyReport>;
 
@@ -96,15 +100,13 @@ declare function detectNamingConventions(files: string[], allIssues: Array<{
 declare function analyzePatterns(filePaths: string[]): Promise<PatternIssue[]>;
 
 /**
- * Calculate AI Readiness Score for code consistency (0-100)
- *
- * Based on:
- * - Issue density (issues per file)
- * - Weighted severity (critical: 10pts, major: 3pts, minor: 0.5pts)
- * - Pattern consistency across codebase
+ * Calculate AI Readiness Score for code consistency (0-100).
  *
- * Includes business value metrics:
- * - Estimated developer hours to fix consistency issues
+ * @param issues - Array of detected consistency issues.
+ * @param totalFilesAnalyzed - Total number of files scanned.
+ * @param costConfig - Optional configuration for productivity cost calculation.
+ * @returns Standardized scoring output for the consistency tool.
+ * @lastUpdated 2026-03-18
  */
 declare function calculateConsistencyScore(issues: ConsistencyIssue[], totalFilesAnalyzed: number, costConfig?: Partial<CostConfig>): ToolScoringOutput;
 

package/dist/index.d.ts

@@ -61,8 +61,12 @@ interface ConsistencyReport {
 }
 
 /**
- * Main consistency analyzer that orchestrates all analysis types
- * Supports: TypeScript, JavaScript, Python, Java, C#, Go
+ * Main consistency analyzer that orchestrates all analysis types.
+ * Supports: TypeScript, JavaScript, Python, Java, C#, Go.
+ *
+ * @param options - Configuration for consistency analysis and file scanning.
+ * @returns Promise resolving to the comprehensive consistency report.
+ * @lastUpdated 2026-03-18
  */
 declare function analyzeConsistency(options: ConsistencyOptions): Promise<ConsistencyReport>;
 
@@ -96,15 +100,13 @@ declare function detectNamingConventions(files: string[], allIssues: Array<{
 declare function analyzePatterns(filePaths: string[]): Promise<PatternIssue[]>;
 
 /**
- * Calculate AI Readiness Score for code consistency (0-100)
- *
- * Based on:
- * - Issue density (issues per file)
- * - Weighted severity (critical: 10pts, major: 3pts, minor: 0.5pts)
- * - Pattern consistency across codebase
+ * Calculate AI Readiness Score for code consistency (0-100).
  *
- * Includes business value metrics:
- * - Estimated developer hours to fix consistency issues
+ * @param issues - Array of detected consistency issues.
+ * @param totalFilesAnalyzed - Total number of files scanned.
+ * @param costConfig - Optional configuration for productivity cost calculation.
+ * @returns Standardized scoring output for the consistency tool.
+ * @lastUpdated 2026-03-18
  */
 declare function calculateConsistencyScore(issues: ConsistencyIssue[], totalFilesAnalyzed: number, costConfig?: Partial<CostConfig>): ToolScoringOutput;
 

package/dist/index.js

@@ -421,7 +421,36 @@ function isCommonAbbreviation(name) {
     "ux",
     "api",
     "env",
-    "url"
+    "url",
+    "req",
+    "res",
+    "err",
+    "ctx",
+    "cb",
+    "idx",
+    "src",
+    "dir",
+    "app",
+    "dev",
+    "qa",
+    "dto",
+    "dao",
+    "ref",
+    "ast",
+    "dom",
+    "log",
+    "msg",
+    "pkg",
+    "req",
+    "err",
+    "res",
+    "css",
+    "html",
+    "xml",
+    "jsx",
+    "tsx",
+    "ts",
+    "js"
   ];
   return common.includes(name.toLowerCase());
 }
@@ -471,6 +500,44 @@ function extractDestructuredIdentifiers(node, isParameter, scopeTracker) {
 // src/analyzers/naming-generalized.ts
 var import_core3 = require("@aiready/core");
 var import_fs2 = require("fs");
+var COMMON_ABBREVIATIONS = /* @__PURE__ */ new Set([
+  "id",
+  "db",
+  "fs",
+  "os",
+  "ip",
+  "ui",
+  "ux",
+  "api",
+  "env",
+  "url",
+  "req",
+  "res",
+  "err",
+  "ctx",
+  "cb",
+  "idx",
+  "src",
+  "dir",
+  "app",
+  "dev",
+  "qa",
+  "dto",
+  "dao",
+  "ref",
+  "ast",
+  "dom",
+  "log",
+  "msg",
+  "pkg",
+  "css",
+  "html",
+  "xml",
+  "jsx",
+  "tsx",
+  "ts",
+  "js"
+]);
 async function analyzeNamingGeneralized(files) {
   const issues = [];
   for (const file of files) {
@@ -478,10 +545,15 @@ async function analyzeNamingGeneralized(files) {
     if (!parser) continue;
     try {
       const code = (0, import_fs2.readFileSync)(file, "utf-8");
+      if (!code.trim()) continue;
       await parser.initialize();
       const result = parser.parse(code, file);
       const conventions = parser.getNamingConventions();
+      const exceptions = new Set(conventions.exceptions || []);
       for (const exp of result.exports) {
+        if (!exp.name || exp.name === "default") continue;
+        if (exceptions.has(exp.name)) continue;
+        if (COMMON_ABBREVIATIONS.has(exp.name.toLowerCase())) continue;
         let pattern;
         if (exp.type === "class") {
           pattern = conventions.classPattern;
@@ -492,7 +564,7 @@ async function analyzeNamingGeneralized(files) {
         } else if (exp.type === "function") {
           pattern = conventions.functionPattern;
         } else if (exp.type === "const") {
-          pattern = conventions.constantPattern;
+          pattern = exp.isPrimitive ? conventions.constantPattern : conventions.variablePattern;
         } else {
           pattern = conventions.variablePattern;
         }
@@ -503,7 +575,8 @@ async function analyzeNamingGeneralized(files) {
             file,
             line: exp.loc?.start.line || 1,
             column: exp.loc?.start.column || 0,
-            severity: import_core3.Severity.Major,
+            // Recalibrate naming issues to Minor to differentiate from structural/architectural issues
+            severity: import_core3.Severity.Minor,
             category: "naming",
             suggestion: `Follow ${parser.language} ${exp.type} naming convention: ${pattern.toString()}`
           });
@@ -511,7 +584,9 @@ async function analyzeNamingGeneralized(files) {
       }
       for (const imp of result.imports) {
         for (const spec of imp.specifiers) {
-          if (spec === "*" || spec === "default") continue;
+          if (!spec || spec === "*" || spec === "default") continue;
+          if (exceptions.has(spec)) continue;
+          if (COMMON_ABBREVIATIONS.has(spec.toLowerCase())) continue;
           if (!conventions.variablePattern.test(spec) && !conventions.classPattern.test(spec)) {
             issues.push({
               type: "naming-inconsistency",
@@ -519,7 +594,8 @@ async function analyzeNamingGeneralized(files) {
               file,
               line: imp.loc?.start.line || 1,
               column: imp.loc?.start.column || 0,
-              severity: import_core3.Severity.Minor,
+              severity: import_core3.Severity.Info,
+              // Reduced from Minor to Info for imports
               category: "naming",
               suggestion: `Imported identifier '${spec}' may not follow standard conventions for this language.`
             });
@@ -527,7 +603,10 @@ async function analyzeNamingGeneralized(files) {
         }
       }
     } catch (error) {
-      console.warn(`Consistency: Failed to analyze ${file}: ${error}`);
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.debug(
+        `Consistency: Skipping unparseable file ${file}: ${errorMessage.split("\\n")[0]}`
+      );
     }
   }
   return issues;

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   analyzeConsistency,
   analyzeNamingAST,
   analyzePatterns
-} from "./chunk-S6BZVTWN.mjs";
+} from "./chunk-TE6JYZD3.mjs";
 
 // src/index.ts
 import { ToolRegistry } from "@aiready/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/consistency",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "description": "Detects consistency issues in naming, patterns, and architecture that confuse AI models",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -43,7 +43,7 @@
     "@typescript-eslint/typescript-estree": "^8.53.0",
     "chalk": "^5.3.0",
     "commander": "^14.0.0",
-    "@aiready/core": "0.23.6"
+    "@aiready/core": "0.23.8"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/analyzer.ts

@@ -15,8 +15,12 @@ import { analyzeNamingGeneralized } from './analyzers/naming-generalized';
 import { analyzePatterns } from './analyzers/patterns';
 
 /**
- * Main consistency analyzer that orchestrates all analysis types
- * Supports: TypeScript, JavaScript, Python, Java, C#, Go
+ * Main consistency analyzer that orchestrates all analysis types.
+ * Supports: TypeScript, JavaScript, Python, Java, C#, Go.
+ *
+ * @param options - Configuration for consistency analysis and file scanning.
+ * @returns Promise resolving to the comprehensive consistency report.
+ * @lastUpdated 2026-03-18
  */
 export async function analyzeConsistency(
   options: ConsistencyOptions
@@ -126,6 +130,13 @@ export async function analyzeConsistency(
   } as unknown as ConsistencyReport;
 }
 
+/**
+ * Check if an issue severity meets the minimum threshold.
+ *
+ * @param severity - The severity of the issue.
+ * @param minSeverity - The minimum severity threshold.
+ * @returns True if severity is greater than or equal to minSeverity.
+ */
 function shouldIncludeSeverity(
   severity: Severity | string,
   minSeverity: Severity | string
@@ -134,7 +145,10 @@ function shouldIncludeSeverity(
 }
 
 /**
- * Map string type to IssueType enum value
+ * Map string type to IssueType enum value.
+ *
+ * @param type - The raw issue type string.
+ * @returns Normalized IssueType enum.
  */
 function getIssueType(type: string | undefined): IssueType {
   if (!type) return IssueType.NamingInconsistency;
@@ -155,7 +169,10 @@ function getIssueType(type: string | undefined): IssueType {
 }
 
 /**
- * Transform NamingIssue or PatternIssue to the required Issue format
+ * Transform NamingIssue or PatternIssue to the required Issue format.
+ *
+ * @param i - The raw issue object to transform.
+ * @returns Standardized Issue object.
  */
 function transformToIssue(i: any): Issue {
   // If already has message and location, return as is

package/src/analyzers/naming-ast.ts

@@ -227,6 +227,35 @@ function isCommonAbbreviation(name: string): boolean {
     'api',
     'env',
     'url',
+    'req',
+    'res',
+    'err',
+    'ctx',
+    'cb',
+    'idx',
+    'src',
+    'dir',
+    'app',
+    'dev',
+    'qa',
+    'dto',
+    'dao',
+    'ref',
+    'ast',
+    'dom',
+    'log',
+    'msg',
+    'pkg',
+    'req',
+    'err',
+    'res',
+    'css',
+    'html',
+    'xml',
+    'jsx',
+    'tsx',
+    'ts',
+    'js',
   ];
   return common.includes(name.toLowerCase());
 }

package/src/analyzers/naming-generalized.ts

@@ -9,6 +9,46 @@ import { getParser, Severity } from '@aiready/core';
 import type { NamingIssue } from '../types';
 import { readFileSync } from 'fs';
 
+// Common abbreviations to whitelist
+const COMMON_ABBREVIATIONS = new Set([
+  'id',
+  'db',
+  'fs',
+  'os',
+  'ip',
+  'ui',
+  'ux',
+  'api',
+  'env',
+  'url',
+  'req',
+  'res',
+  'err',
+  'ctx',
+  'cb',
+  'idx',
+  'src',
+  'dir',
+  'app',
+  'dev',
+  'qa',
+  'dto',
+  'dao',
+  'ref',
+  'ast',
+  'dom',
+  'log',
+  'msg',
+  'pkg',
+  'css',
+  'html',
+  'xml',
+  'jsx',
+  'tsx',
+  'ts',
+  'js',
+]);
+
 /**
  * Analyzes naming conventions using generalized LanguageParser metadata
  */
@@ -23,13 +63,22 @@ export async function analyzeNamingGeneralized(
 
     try {
       const code = readFileSync(file, 'utf-8');
+      if (!code.trim()) continue; // Skip empty files
+
       // Ensure parser is initialized (e.g. WASM loaded)
       await parser.initialize();
       const result = parser.parse(code, file);
       const conventions = parser.getNamingConventions();
+      const exceptions = new Set(conventions.exceptions || []);
 
       // 1. Check Exports
       for (const exp of result.exports) {
+        if (!exp.name || exp.name === 'default') continue;
+        if (exceptions.has(exp.name)) continue;
+
+        // Skip common abbreviations
+        if (COMMON_ABBREVIATIONS.has(exp.name.toLowerCase())) continue;
+
         let pattern: RegExp | undefined;
 
         if (exp.type === 'class') {
@@ -41,7 +90,12 @@ export async function analyzeNamingGeneralized(
         } else if (exp.type === 'function') {
           pattern = conventions.functionPattern;
         } else if (exp.type === 'const') {
-          pattern = conventions.constantPattern;
+          // Only enforce SCREAMING_SNAKE_CASE for primitive constants (strings, numbers,
+          // booleans). Object literals, class instances, and tool definitions are
+          // camelCase by convention (e.g. `logger`, `githubTools`, `RemediationSwarm`).
+          pattern = exp.isPrimitive
+            ? conventions.constantPattern
+            : conventions.variablePattern;
         } else {
           pattern = conventions.variablePattern;
         }
@@ -53,7 +107,8 @@ export async function analyzeNamingGeneralized(
             file,
             line: exp.loc?.start.line || 1,
             column: exp.loc?.start.column || 0,
-            severity: Severity.Major,
+            // Recalibrate naming issues to Minor to differentiate from structural/architectural issues
+            severity: Severity.Minor,
             category: 'naming',
             suggestion: `Follow ${parser.language} ${exp.type} naming convention: ${pattern.toString()}`,
           });
@@ -63,7 +118,9 @@ export async function analyzeNamingGeneralized(
       // 2. Check Imports (basic check for specifier consistency)
       for (const imp of result.imports) {
         for (const spec of imp.specifiers) {
-          if (spec === '*' || spec === 'default') continue;
+          if (!spec || spec === '*' || spec === 'default') continue;
+          if (exceptions.has(spec)) continue;
+          if (COMMON_ABBREVIATIONS.has(spec.toLowerCase())) continue;
 
           if (
             !conventions.variablePattern.test(spec) &&
@@ -76,7 +133,7 @@ export async function analyzeNamingGeneralized(
               file,
               line: imp.loc?.start.line || 1,
               column: imp.loc?.start.column || 0,
-              severity: Severity.Minor,
+              severity: Severity.Info, // Reduced from Minor to Info for imports
               category: 'naming',
               suggestion: `Imported identifier '${spec}' may not follow standard conventions for this language.`,
             });
@@ -84,7 +141,12 @@ export async function analyzeNamingGeneralized(
         }
       }
     } catch (error) {
-      console.warn(`Consistency: Failed to analyze ${file}: ${error}`);
+      // Improved error handling
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      console.debug(
+        `Consistency: Skipping unparseable file ${file}: ${errorMessage.split('\\n')[0]}`
+      );
     }
   }
 

package/src/scoring.ts

@@ -3,15 +3,13 @@ import type { ToolScoringOutput, CostConfig } from '@aiready/core';
 import type { ConsistencyIssue } from './types';
 
 /**
- * Calculate AI Readiness Score for code consistency (0-100)
+ * Calculate AI Readiness Score for code consistency (0-100).
  *
- * Based on:
- * - Issue density (issues per file)
- * - Weighted severity (critical: 10pts, major: 3pts, minor: 0.5pts)
- * - Pattern consistency across codebase
- *
- * Includes business value metrics:
- * - Estimated developer hours to fix consistency issues
+ * @param issues - Array of detected consistency issues.
+ * @param totalFilesAnalyzed - Total number of files scanned.
+ * @param costConfig - Optional configuration for productivity cost calculation.
+ * @returns Standardized scoring output for the consistency tool.
+ * @lastUpdated 2026-03-18
  */
 export function calculateConsistencyScore(
   issues: ConsistencyIssue[],