@aiready/context-analyzer 0.21.6 → 0.21.7

package/src/classifier.ts

@@ -1,4 +1,16 @@
 import type { DependencyNode, FileClassification } from './types';
+import {
+  isBarrelExport,
+  isTypeDefinition,
+  isNextJsPage,
+  isLambdaHandler,
+  isServiceFile,
+  isEmailTemplate,
+  isParserFile,
+  isSessionFile,
+  isUtilityModule,
+  isConfigFile,
+} from './heuristics';
 
 /**
  * Constants for file classifications to avoid magic strings
@@ -99,334 +111,7 @@ export function classifyFile(
   return Classification.UNKNOWN;
 }
 
-/**
- * Detect if a file is a barrel export (index.ts)
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a barrel export
- */
-export function isBarrelExport(node: DependencyNode): boolean {
-  const { file, exports } = node;
-  const fileName = file.split('/').pop()?.toLowerCase();
-
-  // Barrel files are typically named index.ts or index.js
-  const isIndexFile = fileName === 'index.ts' || fileName === 'index.js';
-
-  // Small file with many exports is likely a barrel
-  const isSmallAndManyExports =
-    node.tokenCost < 1000 && (exports || []).length > 5;
-
-  // RE-EXPORT HEURISTIC for non-index files
-  const isReexportPattern =
-    (exports || []).length >= 5 &&
-    (exports || []).every(
-      (e) =>
-        e.type === 'const' ||
-        e.type === 'function' ||
-        e.type === 'type' ||
-        e.type === 'interface'
-    );
-
-  return !!isIndexFile || !!isSmallAndManyExports || !!isReexportPattern;
-}
-
-/**
- * Detect if a file is primarily type definitions
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be primarily types
- */
-export function isTypeDefinition(node: DependencyNode): boolean {
-  const { file } = node;
-
-  // Check file extension
-  if (file.endsWith('.d.ts')) return true;
-
-  // Check if all exports are types or interfaces
-  const nodeExports = node.exports || [];
-  const hasExports = nodeExports.length > 0;
-  const areAllTypes =
-    hasExports &&
-    nodeExports.every((e) => e.type === 'type' || e.type === 'interface');
-  const allTypes: boolean = !!areAllTypes;
-
-  // Check if path includes 'types' or 'interfaces'
-  const isTypePath =
-    file.toLowerCase().includes('/types/') ||
-    file.toLowerCase().includes('/interfaces/') ||
-    file.toLowerCase().includes('/models/');
-
-  return allTypes || (isTypePath && hasExports);
-}
-
-/**
- * Detect if a file is a utility module
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a utility module
- */
-export function isUtilityModule(node: DependencyNode): boolean {
-  const { file } = node;
-
-  // Check if path includes 'utils', 'helpers', etc.
-  const isUtilPath =
-    file.toLowerCase().includes('/utils/') ||
-    file.toLowerCase().includes('/helpers/') ||
-    file.toLowerCase().includes('/util/') ||
-    file.toLowerCase().includes('/helper/');
-
-  const fileName = file.split('/').pop()?.toLowerCase();
-  const isUtilName =
-    fileName?.includes('utils.') ||
-    fileName?.includes('helpers.') ||
-    fileName?.includes('util.') ||
-    fileName?.includes('helper.');
-
-  return !!isUtilPath || !!isUtilName;
-}
-
-/**
- * Detect if a file is a Lambda/API handler
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a Lambda handler
- */
-export function isLambdaHandler(node: DependencyNode): boolean {
-  const { file, exports } = 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('/lambda/') ||
-    file.toLowerCase().includes('/functions/');
-
-  const hasHandlerExport = (exports || []).some(
-    (e) =>
-      e.name.toLowerCase() === 'handler' ||
-      e.name.toLowerCase() === 'main' ||
-      e.name.toLowerCase() === 'lambdahandler' ||
-      e.name.toLowerCase().endsWith('handler')
-  );
-
-  return !!isHandlerName || !!isHandlerPath || !!hasHandlerExport;
-}
-
-/**
- * Detect if a file is a service file
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a service file
- */
-export function isServiceFile(node: DependencyNode): boolean {
-  const { file, exports } = 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 = (exports || []).some(
-    (e) =>
-      e.name.toLowerCase().includes('service') ||
-      e.name.toLowerCase().endsWith('service')
-  );
-  const hasClassExport = (exports || []).some((e) => e.type === 'class');
-
-  return (
-    !!isServiceName ||
-    !!isServicePath ||
-    (!!hasServiceNamedExport && !!hasClassExport)
-  );
-}
-
-/**
- * Detect if a file is an email template/layout
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be an email template
- */
-export function isEmailTemplate(node: DependencyNode): boolean {
-  const { file, exports } = 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 isEmailPath =
-    file.toLowerCase().includes('/emails/') ||
-    file.toLowerCase().includes('/mail/') ||
-    file.toLowerCase().includes('/notifications/');
-
-  const hasTemplateFunction = (exports || []).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')))
-  );
-
-  return !!isEmailPath || !!isEmailTemplateName || !!hasTemplateFunction;
-}
-
-/**
- * Detect if a file is a parser/transformer
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a parser
- */
-export function isParserFile(node: DependencyNode): boolean {
-  const { file, exports } = node;
-  const fileName = file.split('/').pop()?.toLowerCase();
-
-  const parserPatterns = [
-    'parser',
-    '.parser.',
-    '-parser.',
-    '_parser.',
-    'transform',
-    '.transform.',
-    'converter',
-    'mapper',
-    'serializer',
-  ];
-  const isParserName = parserPatterns.some((pattern) =>
-    fileName?.includes(pattern)
-  );
-  const isParserPath =
-    file.toLowerCase().includes('/parsers/') ||
-    file.toLowerCase().includes('/transformers/');
-
-  const hasParseFunction = (exports || []).some(
-    (e) =>
-      e.type === 'function' &&
-      (e.name.toLowerCase().startsWith('parse') ||
-        e.name.toLowerCase().startsWith('transform') ||
-        e.name.toLowerCase().startsWith('extract'))
-  );
-
-  return !!isParserName || !!isParserPath || !!hasParseFunction;
-}
-
-/**
- * Detect if a file is a session/state management file
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a session/state file
- */
-export function isSessionFile(node: DependencyNode): boolean {
-  const { file, exports } = node;
-  const fileName = file.split('/').pop()?.toLowerCase();
-
-  const sessionPatterns = ['session', 'state', 'context', 'store'];
-  const isSessionName = sessionPatterns.some((pattern) =>
-    fileName?.includes(pattern)
-  );
-  const isSessionPath =
-    file.toLowerCase().includes('/sessions/') ||
-    file.toLowerCase().includes('/state/');
-
-  const hasSessionExport = (exports || []).some(
-    (e) =>
-      e.name.toLowerCase().includes('session') ||
-      e.name.toLowerCase().includes('state') ||
-      e.name.toLowerCase().includes('store')
-  );
-
-  return !!isSessionName || !!isSessionPath || !!hasSessionExport;
-}
-
-/**
- * Detect if a file is a configuration or schema file
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a config file
- */
-export function isConfigFile(node: DependencyNode): boolean {
-  const { file, exports } = node;
-  const lowerPath = file.toLowerCase();
-  const fileName = file.split('/').pop()?.toLowerCase();
-
-  const configPatterns = [
-    '.config.',
-    'tsconfig',
-    'jest.config',
-    'package.json',
-    'aiready.json',
-    'next.config',
-    'sst.config',
-  ];
-  const isConfigName = configPatterns.some((p) => fileName?.includes(p));
-  const isConfigPath =
-    lowerPath.includes('/config/') ||
-    lowerPath.includes('/settings/') ||
-    lowerPath.includes('/schemas/');
-
-  const hasSchemaExports = (exports || []).some(
-    (e) =>
-      e.name.toLowerCase().includes('schema') ||
-      e.name.toLowerCase().includes('config') ||
-      e.name.toLowerCase().includes('setting')
-  );
-
-  return !!isConfigName || !!isConfigPath || !!hasSchemaExports;
-}
-
-/**
- * Detect if a file is a Next.js App Router page
- *
- * @param node The dependency node to check
- * @returns True if the file appears to be a Next.js page
- */
-export function isNextJsPage(node: DependencyNode): boolean {
-  const { file, exports } = 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 hasDefaultExport = (exports || []).some((e) => e.type === 'default');
-  const nextJsExports = [
-    'metadata',
-    'generatemetadata',
-    'faqjsonld',
-    'jsonld',
-    'icon',
-  ];
-  const hasNextJsExports = (exports || []).some((e) =>
-    nextJsExports.includes(e.name.toLowerCase())
-  );
-
-  return !!hasDefaultExport || !!hasNextJsExports;
-}
+// [Split Point] Logic below this point handled by heuristics.ts
 
 /**
  * Adjust cohesion score based on file classification

package/src/cli-action.ts

@@ -15,6 +15,13 @@ import {
 import chalk from 'chalk';
 import { writeFileSync } from 'fs';
 
+/**
+ * Orchestrates the context analysis CLI command.
+ * Merges configuration, invokes the analyzer, and formats the output (Console/JSON/HTML).
+ *
+ * @param directory - Root directory to analyze
+ * @param options - CLI options including focus area, max depth, and output format
+ */
 export async function contextActionHandler(directory: string, options: any) {
   console.log(chalk.blue('🔍 Analyzing context window costs...\n'));
 

package/src/cli.ts

@@ -1,23 +1,6 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import { analyzeContext } from './analyzer';
-import { generateSummary } from './summary';
-import {
-  displayConsoleReport,
-  generateHTMLReport,
-  runInteractiveSetup,
-} from './utils/output-formatter';
-import chalk from 'chalk';
-import { writeFileSync } from 'fs';
-import {
-  loadMergedConfig,
-  handleJSONOutput,
-  handleCLIError,
-  getElapsedTime,
-  resolveOutputPath,
-} from '@aiready/core';
-
 import { contextActionHandler } from './cli-action';
 
 const program = new Command();

package/src/cluster-detector.ts

@@ -3,6 +3,10 @@ import { calculateFragmentation, calculateEnhancedCohesion } from './metrics';
 
 /**
  * Group files by domain to detect module clusters
+ * @param graph - The dependency graph to analyze
+ * @param options - Optional configuration options
+ * @param options.useLogScale - Whether to use logarithmic scaling for calculations
+ * @returns Array of module clusters
  */
 export function detectModuleClusters(
   graph: DependencyGraph,
@@ -20,6 +24,29 @@ export function detectModuleClusters(
 
   const clusters: ModuleCluster[] = [];
 
+  const generateSuggestedStructure = (
+    files: string[],
+    tokens: number,
+    fragmentation: number
+  ) => {
+    const targetFiles = Math.max(1, Math.ceil(tokens / 10000));
+    const plan: string[] = [];
+
+    if (fragmentation > 0.5) {
+      plan.push(
+        `Consolidate ${files.length} files scattered across multiple directories into ${targetFiles} core module(s)`
+      );
+    }
+
+    if (tokens > 20000) {
+      plan.push(
+        `Domain logic is very large (${Math.round(tokens / 1000)}k tokens). Ensure clear sub-domain boundaries.`
+      );
+    }
+
+    return { targetFiles, consolidationPlan: plan };
+  };
+
   for (const [domain, files] of domainMap.entries()) {
     if (files.length < 2 || domain === 'unknown') continue;
 

package/src/defaults.ts

@@ -4,6 +4,9 @@ import type { ContextAnalyzerOptions } from './types';
 /**
  * Generate smart defaults for context analysis based on repository size
  * Automatically tunes thresholds to target ~10 most serious issues
+ * @param directory - The root directory to analyze
+ * @param userOptions - Partial user-provided options to merge with defaults
+ * @returns Complete ContextAnalyzerOptions with smart defaults
  */
 export async function getSmartDefaults(
   directory: string,

package/src/graph-builder.ts

@@ -1,4 +1,4 @@
-import { estimateTokens, parseFileExports } from '@aiready/core';
+import { estimateTokens, parseFileExports, FileContent } from '@aiready/core';
 import { singularize } from './utils/string-utils';
 import {
   calculateImportDepthFromEdges,
@@ -14,11 +14,6 @@ import {
 import { extractExportsWithAST } from './ast-utils';
 import { join, dirname, normalize } from 'path';
 
-interface FileContent {
-  file: string;
-  content: string;
-}
-
 /**
  * Resolve an import source to its absolute path considering the importing file's location
  */

package/src/heuristics.ts

@@ -0,0 +1,216 @@
+import { DependencyNode } from './types';
+
+/**
+ * Detect if a file is a barrel export (index.ts)
+ */
+export function isBarrelExport(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const fileName = file.split('/').pop()?.toLowerCase();
+
+  const isIndexFile = fileName === 'index.ts' || fileName === 'index.js';
+  const isSmallAndManyExports =
+    node.tokenCost < 1000 && (exports || []).length > 5;
+
+  const isReexportPattern =
+    (exports || []).length >= 5 &&
+    (exports || []).every((e) =>
+      ['const', 'function', 'type', 'interface'].includes(e.type)
+    );
+
+  return !!isIndexFile || !!isSmallAndManyExports || !!isReexportPattern;
+}
+
+/**
+ * Detect if a file is primarily type definitions
+ */
+export function isTypeDefinition(node: DependencyNode): boolean {
+  const { file } = node;
+  if (file.endsWith('.d.ts')) return true;
+
+  const nodeExports = node.exports || [];
+  const hasExports = nodeExports.length > 0;
+  const areAllTypes =
+    hasExports &&
+    nodeExports.every((e) => e.type === 'type' || e.type === 'interface');
+
+  const isTypePath = /\/(types|interfaces|models)\//i.test(file);
+  return !!areAllTypes || (isTypePath && hasExports);
+}
+
+/**
+ * Detect if a file is a utility module
+ */
+export function isUtilityModule(node: DependencyNode): boolean {
+  const { file } = node;
+  const isUtilPath = /\/(utils|helpers|util|helper)\//i.test(file);
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+  const isUtilName = /(utils\.|helpers\.|util\.|helper\.)/i.test(fileName);
+  return isUtilPath || isUtilName;
+}
+
+/**
+ * Detect if a file is a Lambda/API handler
+ */
+export function isLambdaHandler(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+  const handlerPatterns = [
+    'handler',
+    '.handler.',
+    '-handler.',
+    'lambda',
+    '.lambda.',
+    '-lambda.',
+  ];
+  const isHandlerName = handlerPatterns.some((p) => fileName.includes(p));
+  const isHandlerPath = /\/(handlers|lambdas|lambda|functions)\//i.test(file);
+  const hasHandlerExport = (exports || []).some(
+    (e) =>
+      ['handler', 'main', 'lambdahandler'].includes(e.name.toLowerCase()) ||
+      e.name.toLowerCase().endsWith('handler')
+  );
+  return isHandlerName || isHandlerPath || hasHandlerExport;
+}
+
+/**
+ * Detect if a file is a service file
+ */
+export function isServiceFile(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+  const servicePatterns = ['service', '.service.', '-service.', '_service.'];
+  const isServiceName = servicePatterns.some((p) => fileName.includes(p));
+  const isServicePath = file.toLowerCase().includes('/services/');
+  const hasServiceNamedExport = (exports || []).some((e) =>
+    e.name.toLowerCase().includes('service')
+  );
+  const hasClassExport = (exports || []).some((e) => e.type === 'class');
+  return (
+    isServiceName || isServicePath || (hasServiceNamedExport && hasClassExport)
+  );
+}
+
+/**
+ * Detect if a file is an email template/layout
+ */
+export function isEmailTemplate(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+  const emailPatterns = [
+    '-email-',
+    '.email.',
+    '_email_',
+    '-template',
+    '.template.',
+    '_template',
+    '-mail.',
+    '.mail.',
+  ];
+  const isEmailName = emailPatterns.some((p) => fileName.includes(p));
+  const isEmailPath = /\/(emails|mail|notifications)\//i.test(file);
+  const hasTemplateFunction = (exports || []).some(
+    (e) =>
+      e.type === 'function' &&
+      (e.name.toLowerCase().startsWith('render') ||
+        e.name.toLowerCase().startsWith('generate'))
+  );
+  return isEmailPath || isEmailName || hasTemplateFunction;
+}
+
+/**
+ * Detect if a file is a parser/transformer
+ */
+export function isParserFile(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+  const parserPatterns = [
+    'parser',
+    '.parser.',
+    '-parser.',
+    '_parser.',
+    'transform',
+    'converter',
+    'mapper',
+    'serializer',
+  ];
+  const isParserName = parserPatterns.some((p) => fileName.includes(p));
+  const isParserPath = /\/(parsers|transformers)\//i.test(file);
+  const hasParseFunction = (exports || []).some(
+    (e) =>
+      e.type === 'function' &&
+      (e.name.toLowerCase().startsWith('parse') ||
+        e.name.toLowerCase().startsWith('transform'))
+  );
+  return isParserName || isParserPath || hasParseFunction;
+}
+
+/**
+ * Detect if a file is a session/state management file
+ */
+export function isSessionFile(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+  const sessionPatterns = ['session', 'state', 'context', 'store'];
+  const isSessionName = sessionPatterns.some((p) => fileName.includes(p));
+  const isSessionPath = /\/(sessions|state)\//i.test(file);
+  const hasSessionExport = (exports || []).some((e) =>
+    ['session', 'state', 'store'].some((p) => e.name.toLowerCase().includes(p))
+  );
+  return isSessionName || isSessionPath || hasSessionExport;
+}
+
+/**
+ * Detect if a file is a Next.js App Router page
+ */
+export function isNextJsPage(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const lowerPath = file.toLowerCase();
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+
+  const isInAppDir =
+    lowerPath.includes('/app/') || lowerPath.startsWith('app/');
+  if (!isInAppDir || (fileName !== 'page.tsx' && fileName !== 'page.ts'))
+    return false;
+
+  const hasDefaultExport = (exports || []).some((e) => e.type === 'default');
+  const nextJsExports = [
+    'metadata',
+    'generatemetadata',
+    'faqjsonld',
+    'jsonld',
+    'icon',
+  ];
+  const hasNextJsExport = (exports || []).some((e) =>
+    nextJsExports.includes(e.name.toLowerCase())
+  );
+
+  return hasDefaultExport || hasNextJsExport;
+}
+
+/**
+ * Detect if a file is a configuration or schema file
+ */
+export function isConfigFile(node: DependencyNode): boolean {
+  const { file, exports } = node;
+  const lowerPath = file.toLowerCase();
+  const fileName = file.split('/').pop()?.toLowerCase() || '';
+
+  const configPatterns = [
+    '.config.',
+    'tsconfig',
+    'jest.config',
+    'package.json',
+    'aiready.json',
+    'next.config',
+    'sst.config',
+  ];
+  const isConfigName = configPatterns.some((p) => fileName.includes(p));
+  const isConfigPath = /\/(config|settings|schemas)\//i.test(lowerPath);
+  const hasSchemaExport = (exports || []).some((e) =>
+    ['schema', 'config', 'setting'].some((p) =>
+      e.name.toLowerCase().includes(p)
+    )
+  );
+
+  return isConfigName || isConfigPath || hasSchemaExport;
+}