@aiready/context-analyzer 0.22.9 → 0.22.12

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import { ToolProvider, Severity, ScanOptions, ExportInfo, FileContent, CostConfig, ToolScoringOutput } from '@aiready/core';
+import { ToolProvider, Severity, ScanOptions, ExportInfo, CostConfig, ToolScoringOutput, FileContent } from '@aiready/core';
 export { ExportInfo } from '@aiready/core';
 
 /**
  * Context Analyzer Tool Provider
  */
-declare const ContextAnalyzerProvider: ToolProvider;
+declare const CONTEXT_ANALYZER_PROVIDER: ToolProvider;
 
 /**
  * Options for the Context Analyzer tool.
@@ -152,12 +152,6 @@ interface TypeDependency {
     usedBy: string[];
 }
 
-interface MappingOptions {
-    maxDepth: number;
-    maxContextBudget: number;
-    minCohesion: number;
-    maxFragmentation: number;
-}
 /**
  * Calculate cohesion score (how related are exports in a file).
  * Legacy wrapper for backward compatibility with exact test expectations.
@@ -179,56 +173,24 @@ declare function calculateCohesion(exports: any[], filePath?: string, options?:
 declare function analyzeContext(options: ContextAnalyzerOptions): Promise<ContextAnalysisResult[]>;
 
 /**
- * Auto-detect domain keywords from workspace folder structure.
- *
- * @param files - Array of file contents to analyze for folder patterns.
- * @returns Array of singularized domain keywords.
- */
-declare function extractDomainKeywordsFromPaths(files: FileContent[]): string[];
-/**
- * Build a dependency graph from file contents, resolving imports and extracting metadata.
- *
- * @param files - Array of file contents to process.
- * @param options - Optional configuration for domain detection.
- * @returns Complete dependency graph with nodes, edges, and semantic matrices.
- */
-declare function buildDependencyGraph(files: FileContent[], options?: {
-    domainKeywords?: string[];
-}): Promise<DependencyGraph>;
-/**
- * Calculate the maximum depth of the import tree for a specific file.
- *
- * @param file - File path to start depth calculation from.
- * @param graph - The dependency graph.
- * @param visited - Optional set to track visited nodes during traversal.
- * @param depth - Current recursion depth.
- * @returns Maximum depth of the import chain.
- */
-declare function calculateImportDepth(file: string, graph: DependencyGraph, visited?: Set<string>, depth?: number): number;
-/**
- * Retrieve all transitive dependencies for a specific file.
+ * Calculate AI Readiness Score for context efficiency (0-100).
  *
- * @param file - File path to analyze.
- * @param graph - The dependency graph.
- * @param visited - Optional set to track visited nodes.
- * @returns Array of all reachable file paths.
- */
-declare function getTransitiveDependencies(file: string, graph: DependencyGraph, visited?: Set<string>): string[];
-/**
- * Calculate total context budget (tokens needed to understand this file and its dependencies).
+ * Evaluates how efficiently an AI model can process the project's code context
+ * based on token budgets, import depth, and file fragmentation.
  *
- * @param file - File path to calculate budget for.
- * @param graph - The dependency graph.
- * @returns Total token count including recursive dependencies.
+ * @param summary - Consolidated context summary from the scan.
+ * @param costConfig - Optional configuration for business value calculations.
+ * @returns Standardized scoring output for the context analyzer tool.
+ * @lastUpdated 2026-03-18
  */
-declare function calculateContextBudget(file: string, graph: DependencyGraph): number;
+declare function calculateContextScore(summary: ContextSummary, costConfig?: Partial<CostConfig>): ToolScoringOutput;
 /**
- * Detect circular dependencies (cycles) within the dependency graph.
+ * Maps a numerical score to a human-readable rating slug.
  *
- * @param graph - The dependency graph to scan.
- * @returns Array of dependency cycles (each cycle is an array of file paths).
+ * @param score - The 0-100 readiness score.
+ * @returns A formatted rating string (e.g., "excellent", "at risk").
  */
-declare function detectCircularDependencies(graph: DependencyGraph): string[][];
+declare function mapScoreToRating(score: number): string;
 
 /**
  * Calculates a cohesion score (0-1) for a module based on its exports,
@@ -286,23 +248,61 @@ declare function calculatePathEntropy(files: string[]): number;
 declare function calculateDirectoryDistance(files: string[]): number;
 
 /**
- * Constants for file classifications to avoid magic strings
+ * 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
  */
-declare const Classification: {
-    BARREL: "barrel-export";
-    BOILERPLATE: "boilerplate-barrel";
-    TYPE_DEFINITION: "type-definition";
-    NEXTJS_PAGE: "nextjs-page";
-    LAMBDA_HANDLER: "lambda-handler";
-    SERVICE: "service-file";
-    EMAIL_TEMPLATE: "email-template";
-    PARSER: "parser-file";
-    COHESIVE_MODULE: "cohesive-module";
-    UTILITY_MODULE: "utility-module";
-    SPOKE_MODULE: "spoke-module";
-    MIXED_CONCERNS: "mixed-concerns";
-    UNKNOWN: "unknown";
-};
+declare function detectModuleClusters(graph: DependencyGraph, options?: {
+    useLogScale?: boolean;
+}): ModuleCluster[];
+
+/**
+ * Build a dependency graph from file contents, resolving imports and extracting metadata.
+ *
+ * @param files - Array of file contents to process.
+ * @param options - Optional configuration for domain detection.
+ * @returns Complete dependency graph with nodes, edges, and semantic matrices.
+ */
+declare function buildDependencyGraph(files: FileContent[], options?: {
+    domainKeywords?: string[];
+}): Promise<DependencyGraph>;
+/**
+ * Calculate the maximum depth of the import tree for a specific file.
+ *
+ * @param file - File path to start depth calculation from.
+ * @param graph - The dependency graph.
+ * @param visited - Optional set to track visited nodes during traversal.
+ * @param depth - Current recursion depth.
+ * @returns Maximum depth of the import chain.
+ */
+declare function calculateImportDepth(file: string, graph: DependencyGraph, visited?: Set<string>, depth?: number): number;
+/**
+ * Retrieve all transitive dependencies for a specific file.
+ *
+ * @param file - File path to analyze.
+ * @param graph - The dependency graph.
+ * @param visited - Optional set to track visited nodes.
+ * @returns Array of all reachable file paths.
+ */
+declare function getTransitiveDependencies(file: string, graph: DependencyGraph, visited?: Set<string>): string[];
+/**
+ * Calculate total context budget (tokens needed to understand this file and its dependencies).
+ *
+ * @param file - File path to calculate budget for.
+ * @param graph - The dependency graph.
+ * @returns Total token count including recursive dependencies.
+ */
+declare function calculateContextBudget(file: string, graph: DependencyGraph): number;
+/**
+ * Detect circular dependencies (cycles) within the dependency graph.
+ *
+ * @param graph - The dependency graph to scan.
+ * @returns Array of dependency cycles (each cycle is an array of file paths).
+ */
+declare function detectCircularDependencies(graph: DependencyGraph): string[][];
+
 /**
  * Classify a file into a specific type for better analysis context
  *
@@ -330,17 +330,6 @@ declare function adjustCohesionForClassification(baseCohesion: number, classific
  */
 declare function adjustFragmentationForClassification(baseFragmentation: number, classification: FileClassification): number;
 
-/**
- * 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
- */
-declare function detectModuleClusters(graph: DependencyGraph, options?: {
-    useLogScale?: boolean;
-}): ModuleCluster[];
-
 /**
  * Get classification-specific recommendations
  *
@@ -374,35 +363,6 @@ declare function getGeneralRecommendations(metrics: {
     severity: any;
 };
 
-/**
- * Calculate AI Readiness Score for context efficiency (0-100).
- *
- * Evaluates how efficiently an AI model can process the project's code context
- * based on token budgets, import depth, and file fragmentation.
- *
- * @param summary - Consolidated context summary from the scan.
- * @param costConfig - Optional configuration for business value calculations.
- * @returns Standardized scoring output for the context analyzer tool.
- * @lastUpdated 2026-03-18
- */
-declare function calculateContextScore(summary: ContextSummary, costConfig?: Partial<CostConfig>): ToolScoringOutput;
-/**
- * Maps a numerical score to a human-readable rating slug.
- *
- * @param score - The 0-100 readiness score.
- * @returns A formatted rating string (e.g., "excellent", "at risk").
- */
-declare function mapScoreToRating(score: number): string;
-
-/**
- * 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
- */
-declare function getSmartDefaults(directory: string, userOptions: Partial<ContextAnalyzerOptions>): Promise<ContextAnalyzerOptions>;
-
 /**
  * Generate summary of context analysis results
  *
@@ -412,232 +372,4 @@ declare function getSmartDefaults(directory: string, userOptions: Partial<Contex
  */
 declare function generateSummary(results: ContextAnalysisResult[], options?: any): ContextSummary;
 
-/**
- * Build co-usage matrix: track which files are imported together frequently.
- *
- * @param graph - The dependency graph to analyze.
- * @returns Map of file path to nested map of related files and their co-occurrence counts.
- */
-declare function buildCoUsageMatrix(graph: DependencyGraph): Map<string, Map<string, number>>;
-/**
- * Find semantic clusters using frequently occurring co-usage patterns.
- *
- * @param coUsageMatrix - The co-usage matrix from buildCoUsageMatrix.
- * @param minCoUsage - Minimum co-usage count to consider a strong relationship (default: 3).
- * @returns Map of cluster representative files to their associated cluster members.
- */
-declare function findSemanticClusters(coUsageMatrix: Map<string, Map<string, number>>, minCoUsage?: number): Map<string, string[]>;
-/**
- * Retrieve co-usage data for a specific file.
- *
- * @param file - The file path to look up.
- * @param coUsageMatrix - The global co-usage matrix.
- * @returns Formatted co-usage data object.
- */
-declare function getCoUsageData(file: string, coUsageMatrix: Map<string, Map<string, number>>): CoUsageData;
-
-/**
- * Extract type dependencies from AST exports to build a type-based relationship graph.
- *
- * @param graph - The dependency graph to analyze.
- * @returns Map of type reference names to sets of files that consume or export them.
- */
-declare function buildTypeGraph(graph: DependencyGraph): Map<string, Set<string>>;
-
-/**
- * Calculate confidence score for a domain assignment based on signals.
- *
- * @param signals - The set of semantic signals detected for a domain.
- * @returns Numerical confidence score (0-1).
- */
-declare function calculateDomainConfidence(signals: DomainSignals): number;
-/**
- * Infer domain from semantic analysis (co-usage + types) to identify logical modules.
- *
- * @param file - The file path to infer domain for.
- * @param exportName - The specific export identifier.
- * @param graph - The full dependency graph.
- * @param coUsageMatrix - Matrix of files frequently imported together.
- * @param typeGraph - Map of type references to files.
- * @param exportTypeRefs - Optional list of types referenced by the export.
- * @returns Array of potential domain assignments with confidence scores.
- */
-declare function inferDomainFromSemantics(file: string, exportName: string, graph: DependencyGraph, coUsageMatrix: Map<string, Map<string, number>>, typeGraph: Map<string, Set<string>>, exportTypeRefs?: string[]): DomainAssignment[];
-/**
- * Regex-based export extraction (legacy/fallback)
- *
- * @param content - Source code content.
- * @param filePath - Optional file path for domain context.
- * @param domainOptions - Optional overrides for domain keywords.
- * @param fileImports - Optional list of actual imports for semantic context.
- * @returns Array of extracted export information.
- */
-declare function extractExports(content: string, filePath?: string, domainOptions?: {
-    domainKeywords?: string[];
-}, fileImports?: string[]): ExportInfo[];
-/**
- * Infer domain from name, path, or imports
- *
- * @param name - The identifier name to analyze.
- * @param filePath - Optional file path for structure context.
- * @param domainOptions - Optional overrides for domain keywords.
- * @param fileImports - Optional list of imports for domain context.
- * @returns The inferred domain name (string).
- */
-declare function inferDomain(name: string, filePath?: string, domainOptions?: {
-    domainKeywords?: string[];
-}, fileImports?: string[]): string;
-
-/**
- * Identify candidates for module consolidation based on high co-usage or shared types.
- *
- * @param graph - The dependency graph.
- * @param coUsageMatrix - Matrix of frequently paired files.
- * @param typeGraph - Map of shared type references.
- * @param minCoUsage - Minimum co-usage count threshold.
- * @param minSharedTypes - Minimum shared types threshold.
- * @returns Array of consolidation candidates sorted by strength.
- */
-declare function findConsolidationCandidates(graph: DependencyGraph, coUsageMatrix: Map<string, Map<string, number>>, typeGraph: Map<string, Set<string>>, minCoUsage?: number, minSharedTypes?: number): {
-    files: string[];
-    reason: string;
-    strength: number;
-}[];
-
-/**
- * Classification pattern constants for file type detection.
- */
-/** Minimum exports to consider a file as a barrel export */
-declare const BARREL_EXPORT_MIN_EXPORTS = 5;
-/** Token cost limit for barrel export detection */
-declare const BARREL_EXPORT_TOKEN_LIMIT = 1000;
-/** Patterns for Lambda/API handler detection */
-declare const HANDLER_NAME_PATTERNS: string[];
-/** Patterns for service file detection */
-declare const SERVICE_NAME_PATTERNS: string[];
-/** Patterns for email template detection */
-declare const EMAIL_NAME_PATTERNS: string[];
-/** Patterns for parser/transformer detection */
-declare const PARSER_NAME_PATTERNS: string[];
-/** Patterns for session/state management detection */
-declare const SESSION_NAME_PATTERNS: string[];
-/** Next.js metadata export names */
-declare const NEXTJS_METADATA_EXPORTS: string[];
-/** Patterns for configuration file detection */
-declare const CONFIG_NAME_PATTERNS: string[];
-
-/**
- * Detect if a file is a boilerplate barrel (architectural theater).
- * A boilerplate barrel re-exports from other sources without adding value.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file matches boilerplate barrel patterns.
- */
-declare function isBoilerplateBarrel(node: DependencyNode): boolean;
-/**
- * Detect if a file is a barrel export (index.ts).
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file matches barrel export patterns.
- * @lastUpdated 2026-03-20
- */
-declare function isBarrelExport(node: DependencyNode): boolean;
-/**
- * Detect if a file is primarily type definitions.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file contains primarily types or matches type paths.
- * @lastUpdated 2026-03-18
- */
-declare function isTypeDefinition(node: DependencyNode): boolean;
-/**
- * Detect if a file is a utility module.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file path or name suggests a utility/helper role.
- * @lastUpdated 2026-03-18
- */
-declare function isUtilityModule(node: DependencyNode): boolean;
-/**
- * Detect if a file is a Lambda/API handler.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file serves as a coordination point for requests/lambdas.
- * @lastUpdated 2026-03-18
- */
-declare function isLambdaHandler(node: DependencyNode): boolean;
-/**
- * Detect if a file is a service file.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file orchestrates logic or matches service patterns.
- * @lastUpdated 2026-03-18
- */
-declare function isServiceFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is an email template/layout.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file is used for rendering notifications or emails.
- * @lastUpdated 2026-03-18
- */
-declare function isEmailTemplate(node: DependencyNode): boolean;
-/**
- * Detect if a file is a parser/transformer.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file handles data conversion or serialization.
- * @lastUpdated 2026-03-18
- */
-declare function isParserFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is a session/state management file.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file manages application state or sessions.
- * @lastUpdated 2026-03-18
- */
-declare function isSessionFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is a Next.js App Router page.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file is a Next.js page or metadata entry.
- * @lastUpdated 2026-03-18
- */
-declare function isNextJsPage(node: DependencyNode): boolean;
-/**
- * Detect if a file is a configuration or schema file.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file matches configuration, setting, or schema patterns.
- * @lastUpdated 2026-03-18
- */
-declare function isConfigFile(node: DependencyNode): boolean;
-/**
- * Detect if a file is part of a hub-and-spoke monorepo architecture.
- *
- * Many files spread across multiple packages (spokes) is intentional in
- * AIReady and shouldn't be penalized as heavily for fragmentation.
- *
- * @param node - The dependency node to analyze.
- * @returns True if the file path suggests it belongs to a spoke package.
- */
-declare function isHubAndSpokeFile(node: DependencyNode): boolean;
-
-/**
- * Display analysis report in console
- */
-declare function displayConsoleReport(summary: ReturnType<typeof generateSummary>, results: Awaited<ReturnType<typeof analyzeContext>>, maxResults?: number): void;
-
-/**
- * Generate HTML report
- */
-declare function generateHTMLReport(summary: ReturnType<typeof generateSummary>, results: Awaited<ReturnType<typeof analyzeContext>>): string;
-
-/**
- * Interactive setup: detect common frameworks and suggest excludes & focus areas
- */
-declare function runInteractiveSetup(directory: string, current: any): Promise<any>;
-
-export { BARREL_EXPORT_MIN_EXPORTS, BARREL_EXPORT_TOKEN_LIMIT, CONFIG_NAME_PATTERNS, Classification, type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, ContextAnalyzerProvider, type ContextSummary, type DependencyGraph, type DependencyNode, type DomainAssignment, type DomainSignals, EMAIL_NAME_PATTERNS, type FileClassification, HANDLER_NAME_PATTERNS, type MappingOptions, type ModuleCluster, NEXTJS_METADATA_EXPORTS, PARSER_NAME_PATTERNS, SERVICE_NAME_PATTERNS, SESSION_NAME_PATTERNS, type TypeDependency, adjustCohesionForClassification, adjustFragmentationForClassification, analyzeContext, buildCoUsageMatrix, buildDependencyGraph, buildTypeGraph, calculateCohesion, calculateContextBudget, calculateContextScore, calculateDirectoryDistance, calculateDomainConfidence, calculateEnhancedCohesion, calculateFragmentation, calculateImportDepth, calculatePathEntropy, calculateStructuralCohesionFromCoUsage, classifyFile, detectCircularDependencies, detectModuleClusters, displayConsoleReport, extractDomainKeywordsFromPaths, extractExports, findConsolidationCandidates, findSemanticClusters, generateHTMLReport, generateSummary, getClassificationRecommendations, getCoUsageData, getGeneralRecommendations, getSmartDefaults, getTransitiveDependencies, inferDomain, inferDomainFromSemantics, isBarrelExport, isBoilerplateBarrel, isConfigFile, isEmailTemplate, isHubAndSpokeFile, isLambdaHandler, isNextJsPage, isParserFile, isServiceFile, isSessionFile, isTypeDefinition, isUtilityModule, mapScoreToRating, runInteractiveSetup };
+export { CONTEXT_ANALYZER_PROVIDER, type CoUsageData, type ContextAnalysisResult, type ContextAnalyzerOptions, type ContextSummary, type DependencyGraph, type DependencyNode, type DomainAssignment, type DomainSignals, type FileClassification, type ModuleCluster, type TypeDependency, adjustCohesionForClassification, adjustFragmentationForClassification, analyzeContext, buildDependencyGraph, calculateCohesion, calculateContextBudget, calculateContextScore, calculateDirectoryDistance, calculateEnhancedCohesion, calculateFragmentation, calculateImportDepth, calculatePathEntropy, calculateStructuralCohesionFromCoUsage, classifyFile, detectCircularDependencies, detectModuleClusters, generateSummary, getClassificationRecommendations, getGeneralRecommendations, getTransitiveDependencies, mapScoreToRating };