@aiready/ai-signal-clarity 0.11.21 → 0.12.1

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.12.1 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/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 dist/chunk-2SCIL2EA.mjs 19.32 KB
+ESM dist/cli.mjs            6.83 KB
+ESM ⚡️ Build success in 66ms
+CJS dist/cli.js   28.05 KB
+CJS dist/index.js 22.15 KB
+CJS ⚡️ Build success in 66ms
 DTS Build start
-DTS ⚡️ Build success in 1983ms
+DTS ⚡️ Build success in 1087ms
 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.12.0 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__/scanner-advanced.test.ts (2 tests) 19ms
+ ✓ src/__tests__/scanner.test.ts (6 tests) 26ms
  ✓ src/__tests__/analyzer.test.ts (2 tests) 4ms
- ✓ src/__tests__/scoring.test.ts (2 tests) 2ms
- ✓ src/__tests__/provider.test.ts (2 tests) 8ms
- ✓ 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__/scoring.test.ts (2 tests) 4ms
+ ✓ src/__tests__/provider.test.ts (2 tests) 3ms
+ ✓ src/__tests__/contract.test.ts (1 test) 4ms
 
  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  00:58:49
+   Duration  2.68s (transform 1.64s, setup 0ms, import 9.94s, tests 60ms, environment 1ms)
 
 [?25h

package/dist/chunk-2SCIL2EA.mjs

@@ -0,0 +1,557 @@
+// 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",
+  "undefined",
+  "node",
+  "production",
+  "development",
+  "test",
+  "error",
+  "warn",
+  "info",
+  "debug",
+  "main",
+  "module",
+  "types",
+  "scripts",
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "remove",
+  "delete",
+  "update",
+  "create"
+]);
+var TAILWIND_PATTERN = /^[a-z0-9:-]+(\/[0-9]+)?$/;
+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 (value.length > 20) return false;
+  if (MAGIC_STRING_IGNORE.has(value)) return false;
+  if (TAILWIND_PATTERN.test(value) && value.includes("-")) return false;
+  if (value === value.toUpperCase() && value.length > 3) return false;
+  if (/[/.]/.test(value)) return false;
+  if (/^#[0-9a-fA-F]{3,6}$/.test(value)) return false;
+  return !/^\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, parent, keyInParent) => {
+        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, "");
+            const isKey = node.parent?.type?.includes("pair") || node.parent?.type === "assignment_expression";
+            if (!isKey && 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") {
+            const isNamedConstant = parent?.type === "VariableDeclarator" && parent.id.type === "Identifier" && /^[A-Z0-9_]{3,}$/.test(parent.id.name);
+            const isObjectKey = parent?.type === "Property" && keyInParent === "key";
+            const isJSXClassName = parent?.type === "JSXAttribute" && parent.name?.name === "className";
+            if (isNamedConstant || isObjectKey || isJSXClassName) {
+            } else 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, node);
+          }
+        } 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, node, key)
+                );
+              } else if (typeof child.type === "string") {
+                visitNode(child, node, key);
+              }
+            }
+          }
+        }
+        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
+};