@aiready/consistency 0.2.0

package/dist/index.js

@@ -0,0 +1,415 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  analyzeConsistency: () => analyzeConsistency,
+  analyzeNaming: () => analyzeNaming,
+  analyzePatterns: () => analyzePatterns,
+  detectNamingConventions: () => detectNamingConventions
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/analyzer.ts
+var import_core3 = require("@aiready/core");
+
+// src/analyzers/naming.ts
+var import_core = require("@aiready/core");
+async function analyzeNaming(files) {
+  const issues = [];
+  for (const file of files) {
+    const content = await (0, import_core.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) {
+      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())) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: "abbreviation",
+          identifier: abbrev,
+          severity: "info",
+          suggestion: `Consider using full word instead of abbreviation '${abbrev}'`
+        });
+      }
+    }
+    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];
+      if (!name.match(/^(get|set|is|has|can|should|create|update|delete|fetch|load|save|process|handle|validate|check|find|search|filter|map|reduce)/)) {
+        issues.push({
+          file,
+          line: lineNumber,
+          type: "unclear",
+          identifier: name,
+          severity: "info",
+          suggestion: `Function '${name}' should start with an action verb (get, set, create, etc.)`
+        });
+      }
+    }
+  });
+  return issues;
+}
+function snakeCaseToCamelCase(str) {
+  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
+var import_core2 = require("@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 (0, import_core2.readFileContent)(file);
+    if (content.includes("try {") || content.includes("} catch")) {
+      patterns.tryCatch.push(file);
+    }
+    if (content.match(/throw new \w*Error/)) {
+      patterns.throwsError.push(file);
+    }
+    if (content.match(/return null/)) {
+      patterns.returnsNull.push(file);
+    }
+    if (content.match(/return \{ error:/)) {
+      patterns.returnsError.push(file);
+    }
+  }
+  const issues = [];
+  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 (0, import_core2.readFileContent)(file);
+    if (content.match(/async\s+(function|\(|[a-zA-Z])/)) {
+      patterns.asyncAwait.push(file);
+    }
+    if (content.match(/\.then\(/) || content.match(/\.catch\(/)) {
+      patterns.promises.push(file);
+    }
+    if (content.match(/callback\s*\(/) || content.match(/\(\s*err\s*,/)) {
+      patterns.callbacks.push(file);
+    }
+  }
+  const issues = [];
+  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 (0, import_core2.readFileContent)(file);
+    const hasESM = content.match(/^import\s+/m);
+    const hasCJS = content.match(/require\s*\(/);
+    if (hasESM && hasCJS) {
+      patterns.mixed.push(file);
+    } else if (hasESM) {
+      patterns.esModules.push(file);
+    } else if (hasCJS) {
+      patterns.commonJS.push(file);
+    }
+  }
+  const issues = [];
+  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
+async function analyzeConsistency(options) {
+  const {
+    checkNaming = true,
+    checkPatterns = true,
+    checkArchitecture = false,
+    // Not implemented yet
+    minSeverity = "info",
+    ...scanOptions
+  } = options;
+  const filePaths = await (0, import_core3.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;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  analyzeConsistency,
+  analyzeNaming,
+  analyzePatterns,
+  detectNamingConventions
+});

package/dist/index.mjs

@@ -0,0 +1,12 @@
+import {
+  analyzeConsistency,
+  analyzeNaming,
+  analyzePatterns,
+  detectNamingConventions
+} from "./chunk-CF4LU7KE.mjs";
+export {
+  analyzeConsistency,
+  analyzeNaming,
+  analyzePatterns,
+  detectNamingConventions
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@aiready/consistency",
+  "version": "0.2.0",
+  "description": "Detects consistency issues in naming, patterns, and architecture that confuse AI models",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "aiready-consistency": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "keywords": [
+    "aiready",
+    "consistency",
+    "naming-conventions",
+    "code-patterns",
+    "code-quality",
+    "ai-code",
+    "tech-debt",
+    "refactoring",
+    "copilot",
+    "chatgpt",
+    "claude",
+    "ai-assisted-development",
+    "architecture",
+    "best-practices"
+  ],
+  "author": "AIReady Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/caopengau/aiready-consistency.git"
+  },
+  "homepage": "https://github.com/caopengau/aiready-consistency",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "@aiready/core": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts src/cli.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist",
+    "release": "pnpm build && pnpm publish --no-git-checks"
+  }
+}

package/src/__tests__/analyzer.test.ts

@@ -0,0 +1,127 @@
+import { describe, it, expect } from 'vitest';
+import { analyzeConsistency } from '../analyzer';
+import { analyzeNaming } from '../analyzers/naming';
+import { analyzePatterns } from '../analyzers/patterns';
+
+describe('analyzeConsistency', () => {
+  it('should analyze naming issues', async () => {
+    const report = await analyzeConsistency({
+      rootDir: './src',
+      checkNaming: true,
+      checkPatterns: false,
+    });
+
+    expect(report).toHaveProperty('summary');
+    expect(report).toHaveProperty('results');
+    expect(report).toHaveProperty('recommendations');
+    expect(report.summary).toHaveProperty('namingIssues');
+  });
+
+  it('should detect minimum severity filtering', async () => {
+    const report = await analyzeConsistency({
+      rootDir: './src',
+      minSeverity: 'major',
+    });
+
+    // All issues should be major or critical
+    for (const result of report.results) {
+      for (const issue of result.issues) {
+        expect(['major', 'critical']).toContain(issue.severity);
+      }
+    }
+  });
+});
+
+describe('analyzeNaming', () => {
+  it('should detect single letter variables', () => {
+    const testCode = `
+const x = 10;
+const y = 20;
+const result = x + y;
+`;
+    // In a real test, we'd create temp files or mock file reading
+    // For now, this is a placeholder structure
+    expect(true).toBe(true);
+  });
+
+  it('should detect snake_case in TypeScript files', () => {
+    const testCode = `
+const user_name = 'John';
+const user_id = 123;
+`;
+    // Test would check for convention-mix issues
+    expect(true).toBe(true);
+  });
+
+  it('should detect unclear boolean names', () => {
+    const testCode = `
+const enabled: boolean = true;
+const active: boolean = false;
+`;
+    // Should suggest prefixes like isEnabled, isActive
+    expect(true).toBe(true);
+  });
+
+  it('should allow common abbreviations', () => {
+    const testCode = `
+const id = '123';
+const url = 'https://example.com';
+const api = new ApiClient();
+`;
+    // Should not flag these as issues
+    expect(true).toBe(true);
+  });
+});
+
+describe('analyzePatterns', () => {
+  it('should detect mixed error handling', async () => {
+    // Test would analyze files with different error handling approaches
+    const issues = await analyzePatterns([]);
+    expect(Array.isArray(issues)).toBe(true);
+  });
+
+  it('should detect mixed async patterns', async () => {
+    // Test would check for async/await vs promises vs callbacks
+    const issues = await analyzePatterns([]);
+    expect(Array.isArray(issues)).toBe(true);
+  });
+
+  it('should detect mixed import styles', async () => {
+    // Test would check for ES modules vs CommonJS
+    const issues = await analyzePatterns([]);
+    expect(Array.isArray(issues)).toBe(true);
+  });
+});
+
+describe('consistency scoring', () => {
+  it('should calculate consistency score correctly', () => {
+    // Lower issues = higher score
+    expect(true).toBe(true);
+  });
+
+  it('should weight critical issues more than info', () => {
+    // Critical issues should reduce score more
+    expect(true).toBe(true);
+  });
+});
+
+describe('recommendations', () => {
+  it('should generate relevant recommendations', async () => {
+    const report = await analyzeConsistency({
+      rootDir: './src',
+    });
+
+    expect(Array.isArray(report.recommendations)).toBe(true);
+    expect(report.recommendations.length).toBeGreaterThan(0);
+  });
+
+  it('should suggest standardizing error handling', () => {
+    // When mixed error handling detected
+    expect(true).toBe(true);
+  });
+
+  it('should suggest using async/await consistently', () => {
+    // When mixed async patterns detected
+    expect(true).toBe(true);
+  });
+});