@aiready/context-analyzer 0.9.23 → 0.9.26

package/dist/cli.js

@@ -891,24 +891,50 @@ function calculateDomainCohesion(exports2) {
   return maxEntropy > 0 ? 1 - entropy / maxEntropy : 1;
 }
 function classifyFile(node, cohesionScore, domains) {
-  const { exports: exports2, imports, linesOfCode } = node;
+  const { exports: exports2, imports, linesOfCode, file } = node;
   if (isBarrelExport(node)) {
     return "barrel-export";
   }
   if (isTypeDefinitionFile(node)) {
     return "type-definition";
   }
+  if (isConfigOrSchemaFile(node)) {
+    return "cohesive-module";
+  }
+  if (isLambdaHandler(node)) {
+    return "lambda-handler";
+  }
+  if (isEmailTemplate(node)) {
+    return "email-template";
+  }
+  if (isParserFile(node)) {
+    return "parser-file";
+  }
+  if (isServiceFile(node)) {
+    return "service-file";
+  }
+  if (isSessionFile(node)) {
+    return "cohesive-module";
+  }
+  if (isNextJsPage(node)) {
+    return "nextjs-page";
+  }
+  if (isUtilityFile(node)) {
+    return "utility-module";
+  }
   const uniqueDomains = domains.filter((d) => d !== "unknown");
   const hasSingleDomain = uniqueDomains.length <= 1;
-  const hasHighCohesion = cohesionScore >= 0.7;
-  if (hasSingleDomain && hasHighCohesion) {
+  if (hasSingleDomain) {
     return "cohesive-module";
   }
   const hasMultipleDomains = uniqueDomains.length > 1;
-  const hasLowCohesion = cohesionScore < 0.5;
-  if (hasMultipleDomains || hasLowCohesion) {
+  const hasLowCohesion = cohesionScore < 0.4;
+  if (hasMultipleDomains && hasLowCohesion) {
     return "mixed-concerns";
   }
+  if (cohesionScore >= 0.5) {
+    return "cohesive-module";
+  }
   return "unknown";
 }
 function isBarrelExport(node) {
@@ -933,10 +959,300 @@ function isTypeDefinitionFile(node) {
   const { file, exports: exports2 } = node;
   const fileName = file.split("/").pop()?.toLowerCase();
   const isTypesFile = fileName?.includes("types") || fileName?.includes(".d.ts") || fileName === "types.ts" || fileName === "interfaces.ts";
+  const lowerPath = file.toLowerCase();
+  const isTypesPath = lowerPath.includes("/types/") || lowerPath.includes("/typings/") || lowerPath.includes("/@types/") || lowerPath.startsWith("types/") || lowerPath.startsWith("typings/");
   const typeExports = exports2.filter((e) => e.type === "type" || e.type === "interface");
   const runtimeExports = exports2.filter((e) => e.type === "function" || e.type === "class" || e.type === "const");
   const mostlyTypes = exports2.length > 0 && typeExports.length > runtimeExports.length && typeExports.length / exports2.length > 0.7;
-  return isTypesFile || mostlyTypes;
+  const pureTypeFile = exports2.length > 0 && typeExports.length === exports2.length;
+  const emptyOrReExportInTypesDir = isTypesPath && exports2.length === 0;
+  return isTypesFile || isTypesPath || mostlyTypes || pureTypeFile || emptyOrReExportInTypesDir;
+}
+function isConfigOrSchemaFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const configPatterns = [
+    "config",
+    "schema",
+    "settings",
+    "options",
+    "constants",
+    "env",
+    "environment",
+    ".config.",
+    "-config.",
+    "_config."
+  ];
+  const isConfigName = configPatterns.some(
+    (pattern) => fileName?.includes(pattern) || fileName?.startsWith(pattern) || fileName?.endsWith(`${pattern}.ts`)
+  );
+  const isConfigPath = file.toLowerCase().includes("/config/") || file.toLowerCase().includes("/schemas/") || file.toLowerCase().includes("/settings/");
+  const hasSchemaExports = exports2.some(
+    (e) => e.name.toLowerCase().includes("table") || e.name.toLowerCase().includes("schema") || e.name.toLowerCase().includes("config") || e.name.toLowerCase().includes("setting")
+  );
+  return isConfigName || isConfigPath || hasSchemaExports;
+}
+function isUtilityFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const utilityPatterns = [
+    "util",
+    "utility",
+    "utilities",
+    "helper",
+    "helpers",
+    "common",
+    "shared",
+    "toolbox",
+    "toolkit",
+    ".util.",
+    "-util.",
+    "_util.",
+    "-utils.",
+    ".utils."
+  ];
+  const isUtilityName = utilityPatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isUtilityPath = file.toLowerCase().includes("/utils/") || file.toLowerCase().includes("/helpers/") || file.toLowerCase().includes("/common/") || file.toLowerCase().endsWith("-utils.ts") || file.toLowerCase().endsWith("-util.ts") || file.toLowerCase().endsWith("-helper.ts") || file.toLowerCase().endsWith("-helpers.ts");
+  const hasManySmallExportsInUtilityContext = exports2.length >= 3 && exports2.every((e) => e.type === "function" || e.type === "const") && (isUtilityName || isUtilityPath);
+  return isUtilityName || isUtilityPath || hasManySmallExportsInUtilityContext;
+}
+function isLambdaHandler(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const handlerPatterns = [
+    "handler",
+    ".handler.",
+    "-handler.",
+    "lambda",
+    ".lambda.",
+    "-lambda."
+  ];
+  const isHandlerName = handlerPatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isHandlerPath = file.toLowerCase().includes("/handlers/") || file.toLowerCase().includes("/lambdas/") || file.toLowerCase().includes("/functions/");
+  const hasHandlerExport = exports2.some(
+    (e) => e.name.toLowerCase() === "handler" || e.name.toLowerCase() === "main" || e.name.toLowerCase() === "lambdahandler" || e.name.toLowerCase().endsWith("handler")
+  );
+  const hasSingleEntryInHandlerContext = exports2.length === 1 && (exports2[0].type === "function" || exports2[0].name === "default") && (isHandlerPath || isHandlerName);
+  return isHandlerName || isHandlerPath || hasHandlerExport || hasSingleEntryInHandlerContext;
+}
+function isServiceFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const servicePatterns = [
+    "service",
+    ".service.",
+    "-service.",
+    "_service."
+  ];
+  const isServiceName = servicePatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isServicePath = file.toLowerCase().includes("/services/");
+  const hasServiceNamedExport = exports2.some(
+    (e) => e.name.toLowerCase().includes("service") || e.name.toLowerCase().endsWith("service")
+  );
+  const hasClassExport = exports2.some((e) => e.type === "class");
+  return isServiceName || isServicePath || hasServiceNamedExport && hasClassExport;
+}
+function isEmailTemplate(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const emailTemplatePatterns = [
+    "-email-",
+    ".email.",
+    "_email_",
+    "-template",
+    ".template.",
+    "_template",
+    "-mail.",
+    ".mail."
+  ];
+  const isEmailTemplateName = emailTemplatePatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isSpecificTemplateName = fileName?.includes("receipt") || fileName?.includes("invoice-email") || fileName?.includes("welcome-email") || fileName?.includes("notification-email") || fileName?.includes("writer") && fileName.includes("receipt");
+  const isEmailPath = file.toLowerCase().includes("/emails/") || file.toLowerCase().includes("/mail/") || file.toLowerCase().includes("/notifications/");
+  const hasTemplateFunction = exports2.some(
+    (e) => e.type === "function" && (e.name.toLowerCase().startsWith("render") || e.name.toLowerCase().startsWith("generate") || e.name.toLowerCase().includes("template") && e.name.toLowerCase().includes("email"))
+  );
+  const hasEmailExport = exports2.some(
+    (e) => e.name.toLowerCase().includes("template") && e.type === "function" || e.name.toLowerCase().includes("render") && e.type === "function" || e.name.toLowerCase().includes("email") && e.type !== "class"
+  );
+  return isEmailPath || isEmailTemplateName || isSpecificTemplateName || hasTemplateFunction && hasEmailExport;
+}
+function isParserFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const parserPatterns = [
+    "parser",
+    ".parser.",
+    "-parser.",
+    "_parser.",
+    "transform",
+    ".transform.",
+    "-transform.",
+    "converter",
+    ".converter.",
+    "-converter.",
+    "mapper",
+    ".mapper.",
+    "-mapper.",
+    "serializer",
+    ".serializer.",
+    "deterministic"
+    // For base-parser-deterministic.ts pattern
+  ];
+  const isParserName = parserPatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isParserPath = file.toLowerCase().includes("/parsers/") || file.toLowerCase().includes("/transformers/") || file.toLowerCase().includes("/converters/") || file.toLowerCase().includes("/mappers/");
+  const hasParserExport = exports2.some(
+    (e) => e.name.toLowerCase().includes("parse") || e.name.toLowerCase().includes("transform") || e.name.toLowerCase().includes("convert") || e.name.toLowerCase().includes("map") || e.name.toLowerCase().includes("serialize") || e.name.toLowerCase().includes("deserialize")
+  );
+  const hasParseFunction = exports2.some(
+    (e) => e.type === "function" && (e.name.toLowerCase().startsWith("parse") || e.name.toLowerCase().startsWith("transform") || e.name.toLowerCase().startsWith("convert") || e.name.toLowerCase().startsWith("map") || e.name.toLowerCase().startsWith("extract"))
+  );
+  return isParserName || isParserPath || hasParserExport || hasParseFunction;
+}
+function isSessionFile(node) {
+  const { file, exports: exports2 } = node;
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const sessionPatterns = [
+    "session",
+    ".session.",
+    "-session.",
+    "state",
+    ".state.",
+    "-state.",
+    "context",
+    ".context.",
+    "-context.",
+    "store",
+    ".store.",
+    "-store."
+  ];
+  const isSessionName = sessionPatterns.some(
+    (pattern) => fileName?.includes(pattern)
+  );
+  const isSessionPath = file.toLowerCase().includes("/sessions/") || file.toLowerCase().includes("/state/") || file.toLowerCase().includes("/context/") || file.toLowerCase().includes("/store/");
+  const hasSessionExport = exports2.some(
+    (e) => e.name.toLowerCase().includes("session") || e.name.toLowerCase().includes("state") || e.name.toLowerCase().includes("context") || e.name.toLowerCase().includes("manager") || e.name.toLowerCase().includes("store")
+  );
+  return isSessionName || isSessionPath || hasSessionExport;
+}
+function isNextJsPage(node) {
+  const { file, exports: exports2 } = node;
+  const lowerPath = file.toLowerCase();
+  const fileName = file.split("/").pop()?.toLowerCase();
+  const isInAppDir = lowerPath.includes("/app/") || lowerPath.startsWith("app/");
+  const isPageFile = fileName === "page.tsx" || fileName === "page.ts";
+  if (!isInAppDir || !isPageFile) {
+    return false;
+  }
+  const exportNames = exports2.map((e) => e.name.toLowerCase());
+  const hasDefaultExport = exports2.some((e) => e.type === "default");
+  const nextJsExports = ["metadata", "generatemetadata", "faqjsonld", "jsonld", "icon", "viewport", "dynamic"];
+  const hasNextJsExports = exportNames.some(
+    (name) => nextJsExports.includes(name) || name.includes("jsonld")
+  );
+  return hasDefaultExport || hasNextJsExports;
+}
+function adjustCohesionForClassification(baseCohesion, classification, node) {
+  switch (classification) {
+    case "barrel-export":
+      return 1;
+    case "type-definition":
+      return 1;
+    case "utility-module": {
+      if (node) {
+        const exportNames = node.exports.map((e) => e.name.toLowerCase());
+        const hasRelatedNames = hasRelatedExportNames(exportNames);
+        if (hasRelatedNames) {
+          return Math.min(1, baseCohesion + 0.45);
+        }
+      }
+      return Math.min(1, baseCohesion + 0.35);
+    }
+    case "service-file": {
+      if (node?.exports.some((e) => e.type === "class")) {
+        return Math.min(1, baseCohesion + 0.4);
+      }
+      return Math.min(1, baseCohesion + 0.3);
+    }
+    case "lambda-handler": {
+      if (node) {
+        const hasSingleEntry = node.exports.length === 1 || node.exports.some((e) => e.name.toLowerCase() === "handler");
+        if (hasSingleEntry) {
+          return Math.min(1, baseCohesion + 0.45);
+        }
+      }
+      return Math.min(1, baseCohesion + 0.35);
+    }
+    case "email-template": {
+      if (node) {
+        const hasTemplateFunc = node.exports.some(
+          (e) => e.name.toLowerCase().includes("render") || e.name.toLowerCase().includes("generate") || e.name.toLowerCase().includes("template")
+        );
+        if (hasTemplateFunc) {
+          return Math.min(1, baseCohesion + 0.4);
+        }
+      }
+      return Math.min(1, baseCohesion + 0.3);
+    }
+    case "parser-file": {
+      if (node) {
+        const hasParseFunc = node.exports.some(
+          (e) => e.name.toLowerCase().startsWith("parse") || e.name.toLowerCase().startsWith("transform") || e.name.toLowerCase().startsWith("convert")
+        );
+        if (hasParseFunc) {
+          return Math.min(1, baseCohesion + 0.4);
+        }
+      }
+      return Math.min(1, baseCohesion + 0.3);
+    }
+    case "nextjs-page":
+      return 1;
+    case "cohesive-module":
+      return Math.max(baseCohesion, 0.7);
+    case "mixed-concerns":
+      return baseCohesion;
+    default:
+      return Math.min(1, baseCohesion + 0.1);
+  }
+}
+function hasRelatedExportNames(exportNames) {
+  if (exportNames.length < 2) return true;
+  const stems = /* @__PURE__ */ new Set();
+  const domains = /* @__PURE__ */ new Set();
+  for (const name of exportNames) {
+    const verbs = ["get", "set", "create", "update", "delete", "fetch", "save", "load", "parse", "format", "validate", "convert", "transform", "build", "generate", "render", "send", "receive"];
+    for (const verb of verbs) {
+      if (name.startsWith(verb) && name.length > verb.length) {
+        stems.add(name.slice(verb.length).toLowerCase());
+      }
+    }
+    const domainPatterns = ["user", "order", "product", "session", "email", "file", "db", "s3", "dynamo", "api", "config"];
+    for (const domain of domainPatterns) {
+      if (name.includes(domain)) {
+        domains.add(domain);
+      }
+    }
+  }
+  if (stems.size === 1 && exportNames.length >= 2) return true;
+  if (domains.size === 1 && exportNames.length >= 2) return true;
+  const prefixes = exportNames.map((name) => {
+    const match = name.match(/^([a-z]+)/);
+    return match ? match[1] : "";
+  }).filter((p) => p.length >= 3);
+  if (prefixes.length >= 2) {
+    const uniquePrefixes = new Set(prefixes);
+    if (uniquePrefixes.size === 1) return true;
+  }
+  return false;
 }
 function adjustFragmentationForClassification(baseFragmentation, classification) {
   switch (classification) {
@@ -944,6 +1260,13 @@ function adjustFragmentationForClassification(baseFragmentation, classification)
       return 0;
     case "type-definition":
       return 0;
+    case "utility-module":
+    case "service-file":
+    case "lambda-handler":
+    case "email-template":
+    case "parser-file":
+    case "nextjs-page":
+      return baseFragmentation * 0.2;
     case "cohesive-module":
       return baseFragmentation * 0.3;
     case "mixed-concerns":
@@ -969,6 +1292,36 @@ function getClassificationRecommendations(classification, file, issues) {
         "Module has good cohesion despite its size",
         "Consider documenting the module boundaries for AI assistants"
       ];
+    case "utility-module":
+      return [
+        "Utility module detected - multiple domains are acceptable here",
+        "Consider grouping related utilities by prefix or domain for better discoverability"
+      ];
+    case "service-file":
+      return [
+        "Service file detected - orchestration of multiple dependencies is expected",
+        "Consider documenting service boundaries and dependencies"
+      ];
+    case "lambda-handler":
+      return [
+        "Lambda handler detected - coordination of services is expected",
+        "Ensure handler has clear single responsibility"
+      ];
+    case "email-template":
+      return [
+        "Email template detected - references multiple domains for rendering",
+        "Template structure is cohesive by design"
+      ];
+    case "parser-file":
+      return [
+        "Parser/transformer file detected - handles multiple data sources",
+        "Consider documenting input/output schemas"
+      ];
+    case "nextjs-page":
+      return [
+        "Next.js App Router page detected - metadata/JSON-LD/component pattern is cohesive",
+        "Multiple exports (metadata, faqJsonLd, default) serve single page purpose"
+      ];
     case "mixed-concerns":
       return [
         "Consider splitting this file by domain",
@@ -1091,6 +1444,11 @@ async function analyzeContext(options) {
       ...new Set(node.exports.map((e) => e.inferredDomain || "unknown"))
     ];
     const fileClassification = classifyFile(node, cohesionScore, domains);
+    const adjustedCohesionScore = adjustCohesionForClassification(
+      cohesionScore,
+      fileClassification,
+      node
+    );
     const adjustedFragmentationScore = adjustFragmentationForClassification(
       fragmentationScore,
       fileClassification
@@ -1109,7 +1467,8 @@ async function analyzeContext(options) {
       file,
       importDepth,
       contextBudget,
-      cohesionScore,
+      cohesionScore: adjustedCohesionScore,
+      // Use adjusted cohesion
       fragmentationScore: adjustedFragmentationScore,
       maxDepth,
       maxContextBudget,
@@ -1125,7 +1484,8 @@ async function analyzeContext(options) {
       dependencyCount: dependencyList.length,
       dependencyList,
       circularDeps: circularDeps.filter((cycle) => cycle.includes(file)),
-      cohesionScore,
+      cohesionScore: adjustedCohesionScore,
+      // Report adjusted cohesion
       domains,
       exportCount: node.exports.length,
       contextBudget,

package/dist/cli.mjs

@@ -2,7 +2,7 @@
 import {
   analyzeContext,
   generateSummary
-} from "./chunk-MBE4AQP5.mjs";
+} from "./chunk-PJD4VCIH.mjs";
 import "./chunk-Y6FXYEAI.mjs";
 
 // src/cli.ts

package/dist/index.d.mts

@@ -32,7 +32,7 @@ interface ContextAnalysisResult {
  * Classification of file type for analysis context
  * Helps distinguish real issues from false positives
  */
-type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'mixed-concerns' | 'unknown';
+type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'mixed-concerns' | 'unknown';
 interface ModuleCluster {
     domain: string;
     files: string[];
@@ -130,6 +130,11 @@ interface TypeDependency {
  * - barrel-export: Re-exports from other modules (index.ts files)
  * - type-definition: Primarily type/interface definitions
  * - cohesive-module: Single domain, high cohesion (acceptable large files)
+ * - utility-module: Utility/helper files with cohesive purpose despite multi-domain
+ * - service-file: Service files orchestrating multiple dependencies
+ * - lambda-handler: Lambda/API handlers with single business purpose
+ * - email-template: Email templates/layouts with structural cohesion
+ * - parser-file: Parser/transformer files with single transformation purpose
  * - mixed-concerns: Multiple domains, potential refactoring candidate
  * - unknown: Unable to classify
  */
@@ -141,6 +146,7 @@ declare function classifyFile(node: DependencyNode, cohesionScore: number, domai
  * - Ignoring fragmentation for barrel exports (they're meant to aggregate)
  * - Ignoring fragmentation for type definitions (centralized types are good)
  * - Reducing fragmentation for cohesive modules (large but focused is OK)
+ * - Reducing fragmentation for utility/service/handler/template files
  */
 declare function adjustFragmentationForClassification(baseFragmentation: number, classification: FileClassification): number;
 

package/dist/index.d.ts

@@ -32,7 +32,7 @@ interface ContextAnalysisResult {
  * Classification of file type for analysis context
  * Helps distinguish real issues from false positives
  */
-type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'mixed-concerns' | 'unknown';
+type FileClassification = 'barrel-export' | 'type-definition' | 'cohesive-module' | 'utility-module' | 'service-file' | 'lambda-handler' | 'email-template' | 'parser-file' | 'nextjs-page' | 'mixed-concerns' | 'unknown';
 interface ModuleCluster {
     domain: string;
     files: string[];
@@ -130,6 +130,11 @@ interface TypeDependency {
  * - barrel-export: Re-exports from other modules (index.ts files)
  * - type-definition: Primarily type/interface definitions
  * - cohesive-module: Single domain, high cohesion (acceptable large files)
+ * - utility-module: Utility/helper files with cohesive purpose despite multi-domain
+ * - service-file: Service files orchestrating multiple dependencies
+ * - lambda-handler: Lambda/API handlers with single business purpose
+ * - email-template: Email templates/layouts with structural cohesion
+ * - parser-file: Parser/transformer files with single transformation purpose
  * - mixed-concerns: Multiple domains, potential refactoring candidate
  * - unknown: Unable to classify
  */
@@ -141,6 +146,7 @@ declare function classifyFile(node: DependencyNode, cohesionScore: number, domai
  * - Ignoring fragmentation for barrel exports (they're meant to aggregate)
  * - Ignoring fragmentation for type definitions (centralized types are good)
  * - Reducing fragmentation for cohesive modules (large but focused is OK)
+ * - Reducing fragmentation for utility/service/handler/template files
  */
 declare function adjustFragmentationForClassification(baseFragmentation: number, classification: FileClassification): number;