@aiready/ai-signal-clarity 0.11.21 → 0.12.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
 
 
-> @aiready/ai-signal-clarity@0.11.20 build /Users/pengcao/projects/aiready/packages/ai-signal-clarity
+> @aiready/ai-signal-clarity@0.11.21 build /Users/pengcao/projects/aiready/packages/ai-signal-clarity
 > tsup src/index.ts src/cli.ts --format cjs,esm --dts
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -9,16 +9,16 @@
 CLI Target: es2020
 CJS Build start
 ESM Build start
-ESM dist/chunk-4RIAQ4QQ.mjs 16.98 KB
+ESM dist/chunk-5WOEEOWG.mjs 18.21 KB
 ESM dist/cli.mjs            6.83 KB
 ESM dist/index.mjs          1.40 KB
-ESM ⚡️ Build success in 128ms
-CJS dist/cli.js   25.67 KB
-CJS dist/index.js 19.76 KB
-CJS ⚡️ Build success in 130ms
+ESM ⚡️ Build success in 67ms
+CJS dist/cli.js   26.94 KB
+CJS dist/index.js 21.03 KB
+CJS ⚡️ Build success in 67ms
 DTS Build start
-DTS ⚡️ Build success in 1983ms
+DTS ⚡️ Build success in 1438ms
 DTS dist/cli.d.ts    20.00 B
-DTS dist/index.d.ts  2.80 KB
+DTS dist/index.d.ts  2.90 KB
 DTS dist/cli.d.mts   20.00 B
-DTS dist/index.d.mts 2.80 KB
+DTS dist/index.d.mts 2.90 KB

package/.turbo/turbo-test.log

@@ -1,21 +1,21 @@
 
 
-> @aiready/ai-signal-clarity@0.11.20 test /Users/pengcao/projects/aiready/packages/ai-signal-clarity
+> @aiready/ai-signal-clarity@0.11.21 test /Users/pengcao/projects/aiready/packages/ai-signal-clarity
 > vitest run
 
 [?25l
  RUN  v4.0.18 /Users/pengcao/projects/aiready/packages/ai-signal-clarity
 
- ✓ src/__tests__/analyzer.test.ts (2 tests) 4ms
+ ✓ src/__tests__/provider.test.ts (2 tests) 12ms
+ ✓ src/__tests__/analyzer.test.ts (2 tests) 3ms
  ✓ src/__tests__/scoring.test.ts (2 tests) 2ms
- ✓ src/__tests__/provider.test.ts (2 tests) 8ms
+ ✓ src/__tests__/scanner-advanced.test.ts (2 tests) 33ms
  ✓ src/__tests__/contract.test.ts (1 test) 2ms
- ✓ src/__tests__/scanner-advanced.test.ts (2 tests) 35ms
- ✓ src/__tests__/scanner.test.ts (6 tests) 29ms
+ ✓ src/__tests__/scanner.test.ts (6 tests) 23ms
 
  Test Files  6 passed (6)
       Tests  15 passed (15)
-   Start at  15:19:19
-   Duration  1.07s (transform 477ms, setup 0ms, import 3.40s, tests 79ms, environment 0ms)
+   Start at  18:35:55
+   Duration  1.38s (transform 1.44s, setup 0ms, import 6.01s, tests 75ms, environment 1ms)
 
 [?25h

package/dist/chunk-5WOEEOWG.mjs

@@ -0,0 +1,526 @@
+// src/scanner.ts
+import { readFileSync } from "fs";
+import { getParser, Severity, IssueType } from "@aiready/core";
+var AMBIGUOUS_NAME_PATTERNS = [
+  /^[a-z]$/,
+  // single letter: a, b, x, y
+  /^(tmp|temp|data|obj|val|res|ret|result|item|elem|thing|stuff|info|misc|util|helper|handler|cb|fn|func)$/i,
+  /^[a-z]\d+$/
+  // x1, x2, n3
+];
+var MAGIC_LITERAL_IGNORE = /* @__PURE__ */ new Set([0, 1, -1, 2, 10, 100, 1e3, 1024]);
+var MAGIC_STRING_IGNORE = /* @__PURE__ */ new Set([
+  "",
+  " ",
+  "\n",
+  "	",
+  "utf8",
+  "utf-8",
+  "hex",
+  "base64",
+  "true",
+  "false",
+  "null"
+]);
+function isAmbiguousName(name) {
+  return AMBIGUOUS_NAME_PATTERNS.some((p) => p.test(name));
+}
+function isMagicNumber(value) {
+  return !MAGIC_LITERAL_IGNORE.has(value);
+}
+function isMagicString(value) {
+  if (value.length === 0) return false;
+  if (MAGIC_STRING_IGNORE.has(value)) return false;
+  return value.length <= 20 && !/[/.]/.test(value) && !/^\s+$/.test(value);
+}
+async function scanFile(filePath, options = { rootDir: "." }) {
+  let code;
+  try {
+    code = readFileSync(filePath, "utf-8");
+  } catch {
+    return emptyResult(filePath);
+  }
+  const parser = getParser(filePath);
+  if (!parser) return emptyResult(filePath);
+  try {
+    await parser.initialize();
+    const result = parser.parse(code, filePath);
+    const ast = await parser.getAST(code, filePath);
+    const issues = [];
+    const lineCount = code.split("\n").length;
+    const signals = {
+      magicLiterals: 0,
+      booleanTraps: 0,
+      ambiguousNames: 0,
+      undocumentedExports: 0,
+      implicitSideEffects: 0,
+      deepCallbacks: 0,
+      overloadedSymbols: 0,
+      largeFiles: 0,
+      totalSymbols: result.exports.length + result.imports.length,
+      totalExports: result.exports.length,
+      totalLines: lineCount
+    };
+    const symbolCounts = /* @__PURE__ */ new Map();
+    if (options.checkLargeFiles !== false) {
+      if (lineCount > 750) {
+        signals.largeFiles++;
+        issues.push({
+          type: IssueType.AiSignalClarity,
+          category: "large-file",
+          severity: Severity.Critical,
+          message: `Extreme file length (${lineCount} lines) \u2014 AI context window will overflow or "Lose the Middle" critical details.`,
+          location: { file: filePath, line: 1 },
+          suggestion: "Split into smaller, single-responsibility modules (< 500 lines)."
+        });
+      } else if (lineCount > 500) {
+        signals.largeFiles++;
+        issues.push({
+          type: IssueType.AiSignalClarity,
+          category: "large-file",
+          severity: Severity.Major,
+          message: `Large file (${lineCount} lines) \u2014 pushing the limits of effective AI reasoning.`,
+          location: { file: filePath, line: 1 },
+          suggestion: "Consider refactoring and extracting logic to new files."
+        });
+      }
+    }
+    for (const exp of result.exports) {
+      symbolCounts.set(exp.name, (symbolCounts.get(exp.name) || 0) + 1);
+      if (options.checkUndocumentedExports !== false) {
+        if (!exp.documentation || !exp.documentation.content) {
+          signals.undocumentedExports++;
+          issues.push({
+            type: IssueType.AiSignalClarity,
+            category: "undocumented-export",
+            severity: Severity.Minor,
+            message: `Public export "${exp.name}" has no documentation \u2014 AI fabricates behavior from the name alone.`,
+            location: {
+              file: filePath,
+              line: exp.loc?.start.line || 1,
+              column: exp.loc?.start.column
+            },
+            suggestion: "Add a docstring or comment describing parameters, return value, and side effects."
+          });
+        }
+      }
+      if (options.checkImplicitSideEffects !== false) {
+        if (exp.hasSideEffects && !exp.isPure && exp.type === "function") {
+          const lowerName = exp.name.toLowerCase();
+          const looksPure = !/(set|update|save|delete|create|write|send|post|sync)/.test(
+            lowerName
+          );
+          if (looksPure) {
+            signals.implicitSideEffects++;
+            issues.push({
+              type: IssueType.AiSignalClarity,
+              category: "implicit-side-effect",
+              severity: Severity.Major,
+              message: `Function "${exp.name}" mutates external state but name doesn't reflect it \u2014 AI misses this contract.`,
+              location: {
+                file: filePath,
+                line: exp.loc?.start.line || 1
+              },
+              suggestion: "Make side-effects explicit in function name (e.g., updateX) or return a result."
+            });
+          }
+        }
+      }
+      if (options.checkAmbiguousNames !== false && isAmbiguousName(exp.name)) {
+        signals.ambiguousNames++;
+        issues.push({
+          type: IssueType.AmbiguousApi,
+          category: "ambiguous-name",
+          severity: Severity.Info,
+          message: `Ambiguous public export "${exp.name}" \u2014 AI cannot infer intent and will guess incorrectly.`,
+          location: {
+            file: filePath,
+            line: exp.loc?.start.line || 1
+          },
+          suggestion: "Use a domain-descriptive name instead."
+        });
+      }
+    }
+    if (options.checkOverloadedSymbols !== false) {
+      for (const [name, count] of symbolCounts.entries()) {
+        if (count > 1 && name !== "default" && name !== "anonymous") {
+          signals.overloadedSymbols++;
+          issues.push({
+            type: IssueType.AiSignalClarity,
+            category: "overloaded-symbol",
+            severity: Severity.Critical,
+            message: `Symbol "${name}" has ${count} overloaded signatures \u2014 AI often picks the wrong one or gets confused by conflicting contracts.`,
+            location: {
+              file: filePath,
+              line: 1
+            },
+            suggestion: `Rename overloads to unique, descriptive names if possible.`
+          });
+        }
+      }
+    }
+    if (ast) {
+      let callbackDepth = 0;
+      let maxCallbackDepth = 0;
+      const visitNode = (node) => {
+        if (!node) return;
+        if (options.checkMagicLiterals !== false) {
+          if (node.type === "number") {
+            const val = parseFloat(node.text);
+            if (!isNaN(val) && isMagicNumber(val)) {
+              signals.magicLiterals++;
+              issues.push({
+                type: IssueType.MagicLiteral,
+                category: "magic-literal",
+                severity: Severity.Minor,
+                message: `Magic number ${node.text} \u2014 AI will invent wrong semantics. Extract to a named constant.`,
+                location: {
+                  file: filePath,
+                  line: node.startPosition.row + 1,
+                  column: node.startPosition.column
+                },
+                suggestion: `const MEANINGFUL_NAME = ${node.text};`
+              });
+            }
+          } else if (node.type === "string" || node.type === "string_literal") {
+            const val = node.text.replace(/['"]/g, "");
+            if (isMagicString(val)) {
+              signals.magicLiterals++;
+              issues.push({
+                type: IssueType.MagicLiteral,
+                category: "magic-literal",
+                severity: Severity.Info,
+                message: `Magic string "${val}" \u2014 intent is ambiguous to AI. Consider a named constant.`,
+                location: {
+                  file: filePath,
+                  line: node.startPosition.row + 1
+                }
+              });
+            }
+          } else if (node.type === "Literal") {
+            if (typeof node.value === "number" && isMagicNumber(node.value)) {
+              signals.magicLiterals++;
+              issues.push({
+                type: IssueType.MagicLiteral,
+                category: "magic-literal",
+                severity: Severity.Minor,
+                message: `Magic number ${node.value} \u2014 AI will invent wrong semantics. Extract to a named constant.`,
+                location: {
+                  file: filePath,
+                  line: node.loc?.start.line || 1,
+                  column: node.loc?.start.column
+                },
+                suggestion: `const MEANINGFUL_NAME = ${node.value};`
+              });
+            } else if (typeof node.value === "string" && isMagicString(node.value)) {
+              signals.magicLiterals++;
+              issues.push({
+                type: IssueType.MagicLiteral,
+                category: "magic-literal",
+                severity: Severity.Info,
+                message: `Magic string "${node.value}" \u2014 intent is ambiguous to AI. Consider a named constant.`,
+                location: {
+                  file: filePath,
+                  line: node.loc?.start.line || 1
+                }
+              });
+            }
+          }
+        }
+        if (options.checkBooleanTraps !== false) {
+          if (node.type === "argument_list") {
+            const hasBool = node.namedChildren?.some(
+              (c) => c.type === "true" || c.type === "false" || c.type === "boolean" && (c.text === "true" || c.text === "false")
+            );
+            if (hasBool) {
+              signals.booleanTraps++;
+              issues.push({
+                type: IssueType.BooleanTrap,
+                category: "boolean-trap",
+                severity: Severity.Major,
+                message: `Boolean trap: positional boolean argument at call site. AI inverts intent ~30% of the time.`,
+                location: {
+                  file: filePath,
+                  line: (node.startPosition?.row || 0) + 1
+                },
+                suggestion: "Replace boolean arg with a named options object or separate functions."
+              });
+            }
+          } else if (node.type === "CallExpression") {
+            const hasBool = node.arguments.some(
+              (arg) => arg.type === "Literal" && typeof arg.value === "boolean"
+            );
+            if (hasBool) {
+              signals.booleanTraps++;
+              issues.push({
+                type: IssueType.BooleanTrap,
+                category: "boolean-trap",
+                severity: Severity.Major,
+                message: `Boolean trap: positional boolean argument at call site. AI inverts intent ~30% of the time.`,
+                location: {
+                  file: filePath,
+                  line: node.loc?.start.line || 1
+                },
+                suggestion: "Replace boolean arg with a named options object or separate functions."
+              });
+            }
+          }
+        }
+        if (options.checkAmbiguousNames !== false) {
+          if (node.type === "variable_declarator") {
+            const nameNode = node.childForFieldName("name");
+            if (nameNode && isAmbiguousName(nameNode.text)) {
+              signals.ambiguousNames++;
+              issues.push({
+                type: IssueType.AmbiguousApi,
+                category: "ambiguous-name",
+                severity: Severity.Info,
+                message: `Ambiguous variable name "${nameNode.text}" \u2014 AI intent is unclear.`,
+                location: {
+                  file: filePath,
+                  line: node.startPosition.row + 1
+                }
+              });
+            }
+          } else if (node.type === "VariableDeclarator" && node.id.type === "Identifier") {
+            if (isAmbiguousName(node.id.name)) {
+              signals.ambiguousNames++;
+              issues.push({
+                type: IssueType.AmbiguousApi,
+                category: "ambiguous-name",
+                severity: Severity.Info,
+                message: `Ambiguous variable name "${node.id.name}" \u2014 AI intent is unclear.`,
+                location: {
+                  file: filePath,
+                  line: node.loc?.start.line || 1
+                }
+              });
+            }
+          }
+        }
+        const nodeType = (node.type || "").toLowerCase();
+        const isFunction = nodeType.includes("function") || nodeType.includes("arrow") || nodeType.includes("lambda") || nodeType === "method_declaration";
+        if (isFunction) {
+          callbackDepth++;
+          maxCallbackDepth = Math.max(maxCallbackDepth, callbackDepth);
+        }
+        if (node.namedChildren) {
+          for (const child of node.namedChildren) {
+            visitNode(child);
+          }
+        } else {
+          for (const key in node) {
+            if (key === "parent" || key === "loc" || key === "range") continue;
+            const child = node[key];
+            if (child && typeof child === "object") {
+              if (Array.isArray(child)) {
+                child.forEach(
+                  (c) => c && typeof c.type === "string" && visitNode(c)
+                );
+              } else if (typeof child.type === "string") {
+                visitNode(child);
+              }
+            }
+          }
+        }
+        if (isFunction) {
+          callbackDepth--;
+        }
+      };
+      if (ast.rootNode) {
+        visitNode(ast.rootNode);
+      } else {
+        visitNode(ast);
+      }
+      if (options.checkDeepCallbacks !== false && maxCallbackDepth >= 3) {
+        signals.deepCallbacks = maxCallbackDepth - 2;
+        issues.push({
+          type: IssueType.AiSignalClarity,
+          category: "deep-callback",
+          severity: Severity.Major,
+          message: `Deeply nested logic (depth ${maxCallbackDepth}) \u2014 AI loses control flow context beyond 3 levels.`,
+          location: {
+            file: filePath,
+            line: 1
+          },
+          suggestion: "Extract nested logic into named functions or flatten the structure."
+        });
+      }
+    }
+    return {
+      filePath,
+      issues,
+      signals,
+      fileName: filePath,
+      metrics: {
+        totalSymbols: signals.totalSymbols,
+        totalExports: signals.totalExports
+      }
+    };
+  } catch (error) {
+    console.error(`AI Signal Clarity: Failed to scan ${filePath}: ${error}`);
+    return emptyResult(filePath);
+  }
+}
+function emptyResult(filePath) {
+  return {
+    filePath,
+    issues: [],
+    signals: {
+      magicLiterals: 0,
+      booleanTraps: 0,
+      ambiguousNames: 0,
+      undocumentedExports: 0,
+      implicitSideEffects: 0,
+      deepCallbacks: 0,
+      overloadedSymbols: 0,
+      largeFiles: 0,
+      totalSymbols: 0,
+      totalExports: 0,
+      totalLines: 0
+    },
+    fileName: filePath,
+    metrics: {
+      totalSymbols: 0,
+      totalExports: 0
+    }
+  };
+}
+
+// src/analyzer.ts
+import {
+  scanFiles,
+  calculateAiSignalClarity,
+  Severity as Severity2,
+  emitProgress
+} from "@aiready/core";
+async function analyzeAiSignalClarity(options) {
+  const files = await scanFiles(options);
+  const results = [];
+  const aggregate = {
+    magicLiterals: 0,
+    booleanTraps: 0,
+    ambiguousNames: 0,
+    undocumentedExports: 0,
+    implicitSideEffects: 0,
+    deepCallbacks: 0,
+    overloadedSymbols: 0,
+    largeFiles: 0,
+    totalSymbols: 0,
+    totalExports: 0,
+    totalLines: 0
+  };
+  let processed = 0;
+  for (const filePath of files) {
+    processed++;
+    emitProgress(
+      processed,
+      files.length,
+      "ai-signal-clarity",
+      "analyzing files",
+      options.onProgress
+    );
+    const result = await scanFile(filePath, options);
+    results.push(result);
+    for (const key of Object.keys(aggregate)) {
+      aggregate[key] += result.signals[key] ?? 0;
+    }
+  }
+  const riskResult = calculateAiSignalClarity({
+    overloadedSymbols: aggregate.overloadedSymbols,
+    magicLiterals: aggregate.magicLiterals,
+    booleanTraps: aggregate.booleanTraps,
+    implicitSideEffects: aggregate.implicitSideEffects,
+    deepCallbacks: aggregate.deepCallbacks,
+    ambiguousNames: aggregate.ambiguousNames,
+    undocumentedExports: aggregate.undocumentedExports,
+    largeFiles: aggregate.largeFiles,
+    totalSymbols: Math.max(1, aggregate.totalSymbols),
+    totalExports: Math.max(1, aggregate.totalExports)
+  });
+  const getLevel = (s) => {
+    if (s === Severity2.Critical || s === "critical") return 4;
+    if (s === Severity2.Major || s === "major") return 3;
+    if (s === Severity2.Minor || s === "minor") return 2;
+    if (s === Severity2.Info || s === "info") return 1;
+    return 0;
+  };
+  const allIssues = results.flatMap((r) => r.issues);
+  const criticalSignals = allIssues.filter(
+    (i) => getLevel(i.severity) === 4
+  ).length;
+  const majorSignals = allIssues.filter(
+    (i) => getLevel(i.severity) === 3
+  ).length;
+  const minorSignals = allIssues.filter(
+    (i) => getLevel(i.severity) === 2
+  ).length;
+  const minSev = options.minSeverity ?? Severity2.Info;
+  const filteredResults = results.map((r) => ({
+    ...r,
+    issues: r.issues.filter((i) => getLevel(i.severity) >= getLevel(minSev))
+  }));
+  return {
+    summary: {
+      filesAnalyzed: files.length,
+      totalSignals: allIssues.length,
+      criticalSignals,
+      majorSignals,
+      minorSignals,
+      topRisk: riskResult.topRisk,
+      rating: riskResult.rating
+    },
+    results: filteredResults,
+    aggregateSignals: aggregate,
+    recommendations: riskResult.recommendations
+  };
+}
+
+// src/scoring.ts
+import { calculateAiSignalClarity as calculateAiSignalClarity2, ToolName } from "@aiready/core";
+function calculateAiSignalClarityScore(report) {
+  const { aggregateSignals } = report;
+  const riskResult = calculateAiSignalClarity2({
+    overloadedSymbols: aggregateSignals.overloadedSymbols,
+    magicLiterals: aggregateSignals.magicLiterals,
+    booleanTraps: aggregateSignals.booleanTraps,
+    implicitSideEffects: aggregateSignals.implicitSideEffects,
+    deepCallbacks: aggregateSignals.deepCallbacks,
+    ambiguousNames: aggregateSignals.ambiguousNames,
+    undocumentedExports: aggregateSignals.undocumentedExports,
+    largeFiles: aggregateSignals.largeFiles,
+    totalSymbols: Math.max(1, aggregateSignals.totalSymbols),
+    totalExports: Math.max(1, aggregateSignals.totalExports)
+  });
+  const score = Math.max(0, 100 - riskResult.score);
+  const factors = riskResult.signals.map(
+    (sig) => ({
+      name: sig.name,
+      impact: -sig.riskContribution,
+      description: sig.description
+    })
+  );
+  const recommendations = riskResult.recommendations.map((rec) => ({
+    action: rec,
+    estimatedImpact: 8,
+    priority: riskResult.score > 50 ? "high" : "medium"
+  }));
+  return {
+    toolName: ToolName.AiSignalClarity,
+    score,
+    rawMetrics: {
+      riskScore: riskResult.score,
+      rating: riskResult.rating,
+      topRisk: riskResult.topRisk,
+      ...aggregateSignals
+    },
+    factors,
+    recommendations
+  };
+}
+
+export {
+  scanFile,
+  analyzeAiSignalClarity,
+  calculateAiSignalClarityScore
+};

package/dist/cli.js

@@ -78,6 +78,7 @@ async function scanFile(filePath, options = { rootDir: "." }) {
     const result = parser.parse(code, filePath);
     const ast = await parser.getAST(code, filePath);
     const issues = [];
+    const lineCount = code.split("\n").length;
     const signals = {
       magicLiterals: 0,
       booleanTraps: 0,
@@ -86,10 +87,35 @@ async function scanFile(filePath, options = { rootDir: "." }) {
       implicitSideEffects: 0,
       deepCallbacks: 0,
       overloadedSymbols: 0,
+      largeFiles: 0,
       totalSymbols: result.exports.length + result.imports.length,
-      totalExports: result.exports.length
+      totalExports: result.exports.length,
+      totalLines: lineCount
     };
     const symbolCounts = /* @__PURE__ */ new Map();
+    if (options.checkLargeFiles !== false) {
+      if (lineCount > 750) {
+        signals.largeFiles++;
+        issues.push({
+          type: import_core.IssueType.AiSignalClarity,
+          category: "large-file",
+          severity: import_core.Severity.Critical,
+          message: `Extreme file length (${lineCount} lines) \u2014 AI context window will overflow or "Lose the Middle" critical details.`,
+          location: { file: filePath, line: 1 },
+          suggestion: "Split into smaller, single-responsibility modules (< 500 lines)."
+        });
+      } else if (lineCount > 500) {
+        signals.largeFiles++;
+        issues.push({
+          type: import_core.IssueType.AiSignalClarity,
+          category: "large-file",
+          severity: import_core.Severity.Major,
+          message: `Large file (${lineCount} lines) \u2014 pushing the limits of effective AI reasoning.`,
+          location: { file: filePath, line: 1 },
+          suggestion: "Consider refactoring and extracting logic to new files."
+        });
+      }
+    }
     for (const exp of result.exports) {
       symbolCounts.set(exp.name, (symbolCounts.get(exp.name) || 0) + 1);
       if (options.checkUndocumentedExports !== false) {
@@ -379,8 +405,10 @@ function emptyResult(filePath) {
       implicitSideEffects: 0,
       deepCallbacks: 0,
       overloadedSymbols: 0,
+      largeFiles: 0,
       totalSymbols: 0,
-      totalExports: 0
+      totalExports: 0,
+      totalLines: 0
     },
     fileName: filePath,
     metrics: {
@@ -402,8 +430,10 @@ async function analyzeAiSignalClarity(options) {
     implicitSideEffects: 0,
     deepCallbacks: 0,
     overloadedSymbols: 0,
+    largeFiles: 0,
     totalSymbols: 0,
-    totalExports: 0
+    totalExports: 0,
+    totalLines: 0
   };
   let processed = 0;
   for (const filePath of files) {
@@ -429,6 +459,7 @@ async function analyzeAiSignalClarity(options) {
     deepCallbacks: aggregate.deepCallbacks,
     ambiguousNames: aggregate.ambiguousNames,
     undocumentedExports: aggregate.undocumentedExports,
+    largeFiles: aggregate.largeFiles,
     totalSymbols: Math.max(1, aggregate.totalSymbols),
     totalExports: Math.max(1, aggregate.totalExports)
   });
@@ -482,6 +513,7 @@ function calculateAiSignalClarityScore(report) {
     deepCallbacks: aggregateSignals.deepCallbacks,
     ambiguousNames: aggregateSignals.ambiguousNames,
     undocumentedExports: aggregateSignals.undocumentedExports,
+    largeFiles: aggregateSignals.largeFiles,
     totalSymbols: Math.max(1, aggregateSignals.totalSymbols),
     totalExports: Math.max(1, aggregateSignals.totalExports)
   });

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   analyzeAiSignalClarity,
   calculateAiSignalClarityScore
-} from "./chunk-4RIAQ4QQ.mjs";
+} from "./chunk-5WOEEOWG.mjs";
 
 // src/cli.ts
 import { Command } from "commander";

package/dist/index.d.mts

@@ -13,11 +13,12 @@ interface AiSignalClarityOptions extends ScanOptions {
     checkImplicitSideEffects?: boolean;
     checkDeepCallbacks?: boolean;
     checkOverloadedSymbols?: boolean;
+    checkLargeFiles?: boolean;
     minSeverity?: string;
 }
 interface AiSignalClarityIssue extends Issue {
     type: IssueType.MagicLiteral | IssueType.BooleanTrap | IssueType.AmbiguousApi | IssueType.AiSignalClarity | IssueType.DeadCode;
-    category: 'magic-literal' | 'boolean-trap' | 'ambiguous-name' | 'undocumented-export' | 'implicit-side-effect' | 'deep-callback' | 'overloaded-symbol';
+    category: 'magic-literal' | 'boolean-trap' | 'ambiguous-name' | 'undocumented-export' | 'implicit-side-effect' | 'deep-callback' | 'overloaded-symbol' | 'large-file';
     snippet?: string;
 }
 interface FileAiSignalClarityResult extends AnalysisResult {
@@ -31,8 +32,10 @@ interface FileAiSignalClarityResult extends AnalysisResult {
         implicitSideEffects: number;
         deepCallbacks: number;
         overloadedSymbols: number;
+        largeFiles: number;
         totalSymbols: number;
         totalExports: number;
+        totalLines: number;
     };
 }
 interface AiSignalClarityReport {

package/dist/index.d.ts

@@ -13,11 +13,12 @@ interface AiSignalClarityOptions extends ScanOptions {
     checkImplicitSideEffects?: boolean;
     checkDeepCallbacks?: boolean;
     checkOverloadedSymbols?: boolean;
+    checkLargeFiles?: boolean;
     minSeverity?: string;
 }
 interface AiSignalClarityIssue extends Issue {
     type: IssueType.MagicLiteral | IssueType.BooleanTrap | IssueType.AmbiguousApi | IssueType.AiSignalClarity | IssueType.DeadCode;
-    category: 'magic-literal' | 'boolean-trap' | 'ambiguous-name' | 'undocumented-export' | 'implicit-side-effect' | 'deep-callback' | 'overloaded-symbol';
+    category: 'magic-literal' | 'boolean-trap' | 'ambiguous-name' | 'undocumented-export' | 'implicit-side-effect' | 'deep-callback' | 'overloaded-symbol' | 'large-file';
     snippet?: string;
 }
 interface FileAiSignalClarityResult extends AnalysisResult {
@@ -31,8 +32,10 @@ interface FileAiSignalClarityResult extends AnalysisResult {
         implicitSideEffects: number;
         deepCallbacks: number;
         overloadedSymbols: number;
+        largeFiles: number;
         totalSymbols: number;
         totalExports: number;
+        totalLines: number;
     };
 }
 interface AiSignalClarityReport {

package/dist/index.js

@@ -83,6 +83,7 @@ async function scanFile(filePath, options = { rootDir: "." }) {
     const result = parser.parse(code, filePath);
     const ast = await parser.getAST(code, filePath);
     const issues = [];
+    const lineCount = code.split("\n").length;
     const signals = {
       magicLiterals: 0,
       booleanTraps: 0,
@@ -91,10 +92,35 @@ async function scanFile(filePath, options = { rootDir: "." }) {
       implicitSideEffects: 0,
       deepCallbacks: 0,
       overloadedSymbols: 0,
+      largeFiles: 0,
       totalSymbols: result.exports.length + result.imports.length,
-      totalExports: result.exports.length
+      totalExports: result.exports.length,
+      totalLines: lineCount
     };
     const symbolCounts = /* @__PURE__ */ new Map();
+    if (options.checkLargeFiles !== false) {
+      if (lineCount > 750) {
+        signals.largeFiles++;
+        issues.push({
+          type: import_core.IssueType.AiSignalClarity,
+          category: "large-file",
+          severity: import_core.Severity.Critical,
+          message: `Extreme file length (${lineCount} lines) \u2014 AI context window will overflow or "Lose the Middle" critical details.`,
+          location: { file: filePath, line: 1 },
+          suggestion: "Split into smaller, single-responsibility modules (< 500 lines)."
+        });
+      } else if (lineCount > 500) {
+        signals.largeFiles++;
+        issues.push({
+          type: import_core.IssueType.AiSignalClarity,
+          category: "large-file",
+          severity: import_core.Severity.Major,
+          message: `Large file (${lineCount} lines) \u2014 pushing the limits of effective AI reasoning.`,
+          location: { file: filePath, line: 1 },
+          suggestion: "Consider refactoring and extracting logic to new files."
+        });
+      }
+    }
     for (const exp of result.exports) {
       symbolCounts.set(exp.name, (symbolCounts.get(exp.name) || 0) + 1);
       if (options.checkUndocumentedExports !== false) {
@@ -384,8 +410,10 @@ function emptyResult(filePath) {
       implicitSideEffects: 0,
       deepCallbacks: 0,
       overloadedSymbols: 0,
+      largeFiles: 0,
       totalSymbols: 0,
-      totalExports: 0
+      totalExports: 0,
+      totalLines: 0
     },
     fileName: filePath,
     metrics: {
@@ -407,8 +435,10 @@ async function analyzeAiSignalClarity(options) {
     implicitSideEffects: 0,
     deepCallbacks: 0,
     overloadedSymbols: 0,
+    largeFiles: 0,
     totalSymbols: 0,
-    totalExports: 0
+    totalExports: 0,
+    totalLines: 0
   };
   let processed = 0;
   for (const filePath of files) {
@@ -434,6 +464,7 @@ async function analyzeAiSignalClarity(options) {
     deepCallbacks: aggregate.deepCallbacks,
     ambiguousNames: aggregate.ambiguousNames,
     undocumentedExports: aggregate.undocumentedExports,
+    largeFiles: aggregate.largeFiles,
     totalSymbols: Math.max(1, aggregate.totalSymbols),
     totalExports: Math.max(1, aggregate.totalExports)
   });
@@ -487,6 +518,7 @@ function calculateAiSignalClarityScore(report) {
     deepCallbacks: aggregateSignals.deepCallbacks,
     ambiguousNames: aggregateSignals.ambiguousNames,
     undocumentedExports: aggregateSignals.undocumentedExports,
+    largeFiles: aggregateSignals.largeFiles,
     totalSymbols: Math.max(1, aggregateSignals.totalSymbols),
     totalExports: Math.max(1, aggregateSignals.totalExports)
   });

package/dist/index.mjs

@@ -2,7 +2,7 @@ import {
   analyzeAiSignalClarity,
   calculateAiSignalClarityScore,
   scanFile
-} from "./chunk-4RIAQ4QQ.mjs";
+} from "./chunk-5WOEEOWG.mjs";
 
 // src/index.ts
 import { ToolRegistry } from "@aiready/core";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/ai-signal-clarity",
-  "version": "0.11.21",
+  "version": "0.12.0",
   "description": "Detects code patterns that cause AI models to hallucinate incorrect implementations",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -41,7 +41,7 @@
     "chalk": "^5.3.0",
     "commander": "^14.0.0",
     "glob": "^13.0.0",
-    "@aiready/core": "0.21.21"
+    "@aiready/core": "0.22.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/scoring.test.ts

@@ -16,17 +16,19 @@ describe('AI Signal Clarity Scoring', () => {
     },
     results: [],
     aggregateSignals: {
-      magicLiterals: 60,
+      magicLiterals: 80,
       booleanTraps: 2,
       ambiguousNames: 1,
       undocumentedExports: 3,
       implicitSideEffects: 0,
       deepCallbacks: 0,
       overloadedSymbols: 0,
+      largeFiles: 0,
       totalSymbols: 100,
       totalExports: 20,
+      totalLines: 1000,
     },
-    recommendations: ['Extract 60 magic literals into named constants'],
+    recommendations: ['Extract 80 magic literals into named constants'],
   };
 
   it('should map report to ToolScoringOutput correctly', () => {
@@ -37,7 +39,7 @@ describe('AI Signal Clarity Scoring', () => {
     expect(scoring.score).toBeGreaterThanOrEqual(0);
     expect(scoring.factors.length).toBeGreaterThan(0);
     expect(scoring.recommendations[0].action).toBe(
-      'Extract 60 magic literals into named constants'
+      'Extract 80 magic literals into named constants'
     );
   });
 
@@ -52,8 +54,10 @@ describe('AI Signal Clarity Scoring', () => {
         implicitSideEffects: 0,
         deepCallbacks: 0,
         overloadedSymbols: 0,
+        largeFiles: 0,
         totalSymbols: 100,
         totalExports: 20,
+        totalLines: 100,
       },
     };
 

package/src/analyzer.ts

@@ -32,8 +32,10 @@ export async function analyzeAiSignalClarity(
     implicitSideEffects: 0,
     deepCallbacks: 0,
     overloadedSymbols: 0,
+    largeFiles: 0,
     totalSymbols: 0,
     totalExports: 0,
+    totalLines: 0,
   };
 
   let processed = 0;
@@ -63,6 +65,7 @@ export async function analyzeAiSignalClarity(
     deepCallbacks: aggregate.deepCallbacks,
     ambiguousNames: aggregate.ambiguousNames,
     undocumentedExports: aggregate.undocumentedExports,
+    largeFiles: aggregate.largeFiles,
     totalSymbols: Math.max(1, aggregate.totalSymbols),
     totalExports: Math.max(1, aggregate.totalExports),
   });

package/src/scanner.ts

@@ -81,6 +81,7 @@ export async function scanFile(
     const ast = await parser.getAST(code, filePath);
 
     const issues: AiSignalClarityIssue[] = [];
+    const lineCount = code.split('\n').length;
     const signals = {
       magicLiterals: 0,
       booleanTraps: 0,
@@ -89,13 +90,41 @@ export async function scanFile(
       implicitSideEffects: 0,
       deepCallbacks: 0,
       overloadedSymbols: 0,
+      largeFiles: 0,
       totalSymbols: result.exports.length + result.imports.length,
       totalExports: result.exports.length,
+      totalLines: lineCount,
     };
 
     // Symbol tracking for overloading detection
     const symbolCounts = new Map<string, number>();
 
+    // 0. Check File Size (Large Files)
+    if (options.checkLargeFiles !== false) {
+      if (lineCount > 750) {
+        signals.largeFiles++;
+        issues.push({
+          type: IssueType.AiSignalClarity,
+          category: 'large-file',
+          severity: Severity.Critical,
+          message: `Extreme file length (${lineCount} lines) — AI context window will overflow or "Lose the Middle" critical details.`,
+          location: { file: filePath, line: 1 },
+          suggestion:
+            'Split into smaller, single-responsibility modules (< 500 lines).',
+        });
+      } else if (lineCount > 500) {
+        signals.largeFiles++;
+        issues.push({
+          type: IssueType.AiSignalClarity,
+          category: 'large-file',
+          severity: Severity.Major,
+          message: `Large file (${lineCount} lines) — pushing the limits of effective AI reasoning.`,
+          location: { file: filePath, line: 1 },
+          suggestion: 'Consider refactoring and extracting logic to new files.',
+        });
+      }
+    }
+
     // 1. Check Metadata-based signals (Side Effects, Docs, Overloads)
     for (const exp of result.exports) {
       // Overload tracking
@@ -448,8 +477,10 @@ function emptyResult(filePath: string): FileAiSignalClarityResult {
       implicitSideEffects: 0,
       deepCallbacks: 0,
       overloadedSymbols: 0,
+      largeFiles: 0,
       totalSymbols: 0,
       totalExports: 0,
+      totalLines: 0,
     },
     fileName: filePath,
     metrics: {

package/src/scoring.ts

@@ -22,6 +22,7 @@ export function calculateAiSignalClarityScore(
     deepCallbacks: aggregateSignals.deepCallbacks,
     ambiguousNames: aggregateSignals.ambiguousNames,
     undocumentedExports: aggregateSignals.undocumentedExports,
+    largeFiles: aggregateSignals.largeFiles,
     totalSymbols: Math.max(1, aggregateSignals.totalSymbols),
     totalExports: Math.max(1, aggregateSignals.totalExports),
   });

package/src/types.ts

@@ -13,6 +13,7 @@ export interface AiSignalClarityOptions extends ScanOptions {
   checkImplicitSideEffects?: boolean;
   checkDeepCallbacks?: boolean;
   checkOverloadedSymbols?: boolean;
+  checkLargeFiles?: boolean;
   minSeverity?: string;
 }
 
@@ -30,7 +31,8 @@ export interface AiSignalClarityIssue extends Issue {
     | 'undocumented-export'
     | 'implicit-side-effect'
     | 'deep-callback'
-    | 'overloaded-symbol';
+    | 'overloaded-symbol'
+    | 'large-file';
   snippet?: string;
 }
 
@@ -45,8 +47,10 @@ export interface FileAiSignalClarityResult extends AnalysisResult {
     implicitSideEffects: number;
     deepCallbacks: number;
     overloadedSymbols: number;
+    largeFiles: number;
     totalSymbols: number;
     totalExports: number;
+    totalLines: number;
   };
 }