Press n or j to go to the next uncovered block, b, p or k for the previous block.
| 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | import type { ScanOptions, Severity } from '@aiready/core';
/**
* Options for the Context Analyzer tool.
* Controls thresholds for import depth, context budget, and cohesion.
*/
export interface ContextAnalyzerOptions extends ScanOptions {
/** Maximum acceptable import depth (default: 5) */
maxDepth?: number;
/** Maximum acceptable token budget for a single context (default: 25000) */
maxContextBudget?: number;
/** Minimum acceptable cohesion score between 0 and 1 (default: 0.6) */
minCohesion?: number;
/** Maximum acceptable fragmentation score between 0 and 1 (default: 0.5) */
maxFragmentation?: number;
/** Analysis focus area: fragmentation, cohesion, depth, or all (default: 'all') */
focus?: 'fragmentation' | 'cohesion' | 'depth' | 'all';
/** Whether to include node_modules in the analysis (default: false) */
includeNodeModules?: boolean;
}
/**
* The result of a context analysis for a single file or module.
* Includes metrics for tokens, dependencies, cohesion, and AI impact.
*/
export interface ContextAnalysisResult {
/** The file path being analyzed */
file: string;
// Basic metrics
/** Total number of tokens in this file */
tokenCost: number;
/** Total lines of code in the file */
linesOfCode: number;
// Dependency analysis
/** Maximum depth of the import tree for this file */
importDepth: number;
/** Total number of transitive dependencies */
dependencyCount: number;
/** List of all files in the dependency tree */
dependencyList: string[];
/** Detected circular dependency chains */
circularDeps: string[][];
// Cohesion analysis
/** Cohesion score from 0 to 1 (1 is perfect cohesion) */
cohesionScore: number;
/** Detected domain categories for the module */
domains: string[];
/** Number of exported symbols */
exportCount: number;
// AI context impact
/** Total tokens required to understand this file and all its dependencies */
contextBudget: number;
/** Fragmentation score from 0 to 1 (0 is well-grouped) */
fragmentationScore: number;
/** List of files that should be loaded together for full context */
relatedFiles: string[];
// File classification (NEW)
/** The semantic classification of the file (e.g. 'barrel-export', 'service-file') */
fileClassification: FileClassification;
// Recommendations
/** Overall severity of identified issues */
severity: Severity | 'critical' | 'major' | 'minor' | 'info';
/** List of specific structural problems found */
issues: string[];
/** Actionable suggestions for improving context readiness */
recommendations: string[];
/** Estimated tokens that could be saved by following recommendations */
potentialSavings: number;
}
/**
* Classification of file type for analysis context
* Helps distinguish real issues from false positives
*/
export type FileClassification =
| 'barrel-export' // Re-exports from other modules (index.ts files)
| 'boilerplate-barrel' // Redundant barrel file with no added value (architectural theater)
| '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
| 'nextjs-page' // Next.js App Router page with SEO/structured data exports
| 'spoke-module' // Intentional monorepo spoke package file
| 'mixed-concerns' // Multiple domains, potential refactoring candidate
| 'unknown'; // Unable to classify
export interface ModuleCluster {
domain: string; // e.g., "user-management", "auth"
files: string[];
totalTokens: number;
fragmentationScore: number; // 0-1, higher = more scattered
pathEntropy?: number; // normalized [0-1] Shannon entropy of directory distribution
directoryDistance?: number; // normalized [0-1] based on common ancestor depth
importCohesion?: number; // 0-1 average pairwise Jaccard similarity of imports
avgCohesion: number; // Average cohesion across files in cluster
suggestedStructure: {
targetFiles: number; // Recommended number of files
consolidationPlan: string[]; // Step-by-step suggestions
};
}
export interface ContextSummary {
totalFiles: number;
totalTokens: number;
avgContextBudget: number;
maxContextBudget: number;
// Depth metrics
avgImportDepth: number;
maxImportDepth: number;
deepFiles: Array<{ file: string; depth: number }>; // Files exceeding maxDepth
// Fragmentation metrics
avgFragmentation: number;
fragmentedModules: ModuleCluster[];
// Cohesion metrics
avgCohesion: number;
lowCohesionFiles: Array<{ file: string; score: number }>;
// Issues summary
criticalIssues: number;
majorIssues: number;
minorIssues: number;
totalPotentialSavings: number;
// Top offenders
topExpensiveFiles: Array<{
file: string;
contextBudget: number;
severity: string;
}>;
config?: any;
}
export interface DependencyGraph {
nodes: Map<string, DependencyNode>;
edges: Map<string, Set<string>>; // file -> dependencies
coUsageMatrix?: Map<string, Map<string, number>>; // file -> file -> co-usage count
typeGraph?: Map<string, Set<string>>; // type -> files that reference it
}
export interface DependencyNode {
file: string;
imports: string[]; // Direct imports
exports: ExportInfo[];
tokenCost: number;
linesOfCode: number;
exportedBy?: string[]; // Files that import exports from this file
sharedTypes?: string[]; // Types shared with other files
}
export interface ExportInfo {
name: string;
type: 'function' | 'class' | 'const' | 'type' | 'interface' | 'default';
inferredDomain?: string; // Inferred from name/usage (legacy single domain)
domains?: DomainAssignment[]; // Multi-domain support with confidence scores
imports?: string[]; // Imports used by this export (for import-based cohesion)
dependencies?: string[]; // Other exports from same file this depends on
typeReferences?: string[]; // TypeScript types referenced by this export
}
export interface DomainAssignment {
domain: string;
confidence: number; // 0-1, how confident are we in this assignment
signals: DomainSignals; // Which signals contributed to this assignment
}
export interface DomainSignals {
folderStructure: boolean; // Matched from folder name
importPath: boolean; // Matched from import paths
typeReference: boolean; // Matched from TypeScript type usage
coUsage: boolean; // Matched from co-usage patterns
exportName: boolean; // Matched from export identifier name
}
export interface CoUsageData {
file: string;
coImportedWith: Map<string, number>; // file -> count of times imported together
sharedImporters: string[]; // files that import both this and another file
}
export interface TypeDependency {
typeName: string;
definedIn: string; // file where type is defined
usedBy: string[]; // files that reference this type
}
|