fcis 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,709 @@
+import { SourceFile, Project } from 'ts-morph';
+
+/**
+ * Core type definitions for the FCIS Analyzer
+ *
+ * These types form the contract between the analyzer's layers:
+ * - Extraction layer produces ExtractedFunction and FileImports
+ * - Detection layer produces ImpurityMarker[]
+ * - Classification layer produces ClassifiedFunction
+ * - Scoring layer produces FileScore, DirectoryScore, ProjectScore
+ */
+/**
+ * CallSite captures position and context for each call expression,
+ * enabling sequence analysis (GATHER→DECIDE→EXECUTE detection)
+ */
+type CallSite = {
+    expression: string;
+    line: number;
+    isAwaited: boolean;
+};
+/**
+ * Represents a function extracted from source code
+ */
+type ExtractedFunction = {
+    name: string | null;
+    filePath: string;
+    startLine: number;
+    endLine: number;
+    isAsync: boolean;
+    isExported: boolean;
+    bodyLineCount: number;
+    statementCount: number;
+    hasConditionals: boolean;
+    parentContext: string | null;
+    callSites: CallSite[];
+    hasAwait: boolean;
+    propertyAccessChains: string[];
+    kind: 'function' | 'method' | 'arrow' | 'function-expression' | 'getter' | 'setter';
+};
+/**
+ * Represents imports in a file
+ */
+type FileImports = {
+    filePath: string;
+    imports: {
+        moduleSpecifier: string;
+        namedImports: string[];
+    }[];
+};
+/**
+ * Strict marker type union — prevents typos, enables exhaustive matching
+ * Note: 'async-function' removed — async alone is not an impurity marker
+ * Note: React hook markers deferred to v2
+ */
+type MarkerType = 'await-expression' | 'database-call' | 'network-fetch' | 'network-http' | 'fs-import' | 'fs-call' | 'env-access' | 'console-log' | 'logging' | 'telemetry' | 'queue-enqueue' | 'event-emit';
+/**
+ * Represents a detected impurity marker in a function
+ */
+type ImpurityMarker = {
+    type: MarkerType;
+    detail: string;
+    line?: number;
+};
+/**
+ * Binary classification — objective, no heuristics
+ */
+type FunctionClassification = 'pure' | 'impure';
+/**
+ * Derived status for UX — actionable guidance
+ */
+type Status = 'ok' | 'review' | 'refactor';
+/**
+ * A function that has been classified with markers, classification, quality score, and status
+ */
+type ClassifiedFunction = ExtractedFunction & {
+    markers: ImpurityMarker[];
+    classification: FunctionClassification;
+    qualityScore: number | null;
+    status: Status;
+};
+/**
+ * Breakdown of function statuses
+ */
+type StatusBreakdown = {
+    ok: number;
+    review: number;
+    refactor: number;
+};
+/**
+ * Refactoring candidate summary for reporting
+ */
+type RefactoringCandidate = {
+    name: string | null;
+    filePath: string;
+    startLine: number;
+    bodyLineCount: number;
+    qualityScore: number;
+    markers: MarkerType[];
+};
+/**
+ * Score for a single file
+ */
+type FileScore = {
+    filePath: string;
+    purity: number;
+    impurityQuality: number | null;
+    health: number;
+    pureCount: number;
+    impureCount: number;
+    excludedCount: number;
+    statusBreakdown: StatusBreakdown;
+    pureLineCount: number;
+    impureLineCount: number;
+    functions: ClassifiedFunction[];
+    refactoringCandidates: Omit<RefactoringCandidate, 'filePath'>[];
+    allExcluded?: boolean;
+    typeOnly?: boolean;
+};
+/**
+ * Score for a directory
+ */
+type DirectoryScore = {
+    dirPath: string;
+    purity: number;
+    impurityQuality: number | null;
+    health: number;
+    pureCount: number;
+    impureCount: number;
+    excludedCount: number;
+    statusBreakdown: StatusBreakdown;
+    pureLineCount: number;
+    impureLineCount: number;
+    fileScores: FileScore[];
+};
+/**
+ * Project-level score (top-level output)
+ */
+type ProjectScore = {
+    purity: number;
+    impurityQuality: number | null;
+    health: number;
+    pureCount: number;
+    impureCount: number;
+    excludedCount: number;
+    statusBreakdown: StatusBreakdown;
+    pureLineCount: number;
+    impureLineCount: number;
+    directoryScores: DirectoryScore[];
+    timestamp: string;
+    commitHash: string | null;
+    refactoringCandidates: RefactoringCandidate[];
+    allExcluded?: boolean;
+    subset?: boolean;
+    filesGlob?: string;
+    errors?: AnalysisError[];
+};
+/**
+ * Error encountered during analysis
+ */
+type AnalysisError = {
+    filePath: string;
+    error: string;
+};
+/**
+ * Configuration options for the analyzer
+ */
+type AnalyzerConfig = {
+    tsconfigPath: string;
+    filesGlob?: string;
+    minHealth?: number;
+    minPurity?: number;
+    minQuality?: number;
+    format?: 'console' | 'json' | 'summary';
+    outputPath?: string;
+    quiet?: boolean;
+    verbose?: boolean;
+};
+/**
+ * Quality scoring thresholds (configurable)
+ */
+type QualityThresholds = {
+    okThreshold: number;
+    reviewThreshold: number;
+};
+/**
+ * Default quality thresholds
+ */
+declare const DEFAULT_QUALITY_THRESHOLDS: QualityThresholds;
+/**
+ * Result of extracting functions from a file
+ */
+type ExtractionResult = {
+    filePath: string;
+    functions: ExtractedFunction[];
+    imports: FileImports;
+    isTypeOnly: boolean;
+    error?: string;
+};
+/**
+ * Detection context passed to marker detection
+ */
+type DetectionContext = {
+    imports: FileImports;
+    pureFileImports: Set<string>;
+};
+
+/**
+ * Analyzer - Main Orchestration Layer (Shell)
+ *
+ * This module orchestrates the full analysis pipeline:
+ * 1. Load project via ts-morph
+ * 2. Extract functions from source files
+ * 3. Detect impurity markers
+ * 4. Classify functions
+ * 5. Compute quality scores
+ * 6. Aggregate into file, directory, and project scores
+ *
+ * This is a SHELL module - it coordinates I/O and calls pure functions.
+ */
+
+/**
+ * Run the full analysis pipeline
+ *
+ * @param config - Analyzer configuration
+ * @returns Project score with all metrics
+ */
+declare function analyze(config: AnalyzerConfig): Promise<ProjectScore>;
+/**
+ * Analyze a single source file
+ *
+ * @param sourceFile - The ts-morph source file to analyze
+ * @returns FileScore with all metrics
+ */
+declare function analyzeFile(sourceFile: SourceFile): FileScore;
+/**
+ * Analyze a single file from a file path (convenience function)
+ *
+ * @param tsconfigPath - Path to tsconfig.json
+ * @param filePath - Path to the file to analyze
+ * @returns FileScore with all metrics
+ */
+declare function analyzeFilePath(tsconfigPath: string, filePath: string): Promise<FileScore | null>;
+/**
+ * Check if analysis passes thresholds
+ *
+ * @param score - Project score to check
+ * @param config - Configuration with threshold values
+ * @returns Object indicating pass/fail status and messages
+ */
+declare function checkThresholds(score: ProjectScore, config: Pick<AnalyzerConfig, 'minHealth' | 'minPurity' | 'minQuality'>): {
+    passed: boolean;
+    failures: string[];
+};
+
+/**
+ * Detect all impurity markers in a function
+ *
+ * @param fn - The extracted function to analyze
+ * @param context - Detection context including imports
+ * @returns Array of detected impurity markers
+ */
+declare function detectMarkers(fn: ExtractedFunction, context: DetectionContext): ImpurityMarker[];
+/**
+ * Create detection context from file imports
+ */
+declare function createDetectionContext(imports: FileImports): DetectionContext;
+/**
+ * Get the names of functions imported from .pure files
+ */
+declare function getPureImportedFunctions(context: DetectionContext): Set<string>;
+
+/**
+ * Marker Definitions and Catalog
+ *
+ * This module defines the impurity marker types and provides a catalog
+ * of patterns for detecting each marker type. This is PURE code - all
+ * functions take data in and return data out with no I/O.
+ *
+ * The marker catalog is defined as a data structure to enable:
+ * - Extensibility (custom markers can be added)
+ * - Documentation (each marker has a description)
+ * - Testing (patterns can be validated in isolation)
+ */
+
+/**
+ * Marker definition with detection patterns
+ */
+type MarkerDefinition = {
+    type: MarkerType;
+    description: string;
+    category: 'io' | 'state' | 'side-effect' | 'environment';
+    severity: 'high' | 'medium' | 'low';
+};
+/**
+ * Marker catalog - all recognized impurity markers
+ */
+declare const MARKER_CATALOG: Record<MarkerType, MarkerDefinition>;
+/**
+ * Get marker definition by type
+ */
+declare function getMarkerDefinition(type: MarkerType): MarkerDefinition;
+/**
+ * Get all marker types
+ */
+declare function getAllMarkerTypes(): MarkerType[];
+
+/**
+ * Function Classifier - Pure Core
+ *
+ * Classifies functions as pure or impure based on their markers.
+ * This is a PURE module - all functions take data in and return data out.
+ *
+ * Classification is binary and objective:
+ * - Pure: Zero I/O markers
+ * - Impure: Has one or more I/O markers
+ *
+ * Note: `async` without `await` (and without other I/O markers) is still pure.
+ */
+
+/**
+ * Classify a function based on its markers
+ *
+ * @param fn - The extracted function
+ * @param markers - Detected impurity markers
+ * @returns The function classification ('pure' or 'impure')
+ */
+declare function classifyFunction(_fn: ExtractedFunction, markers: ImpurityMarker[]): FunctionClassification;
+/**
+ * Check if a function should be excluded from scoring
+ *
+ * Excluded functions:
+ * - Trivial functions (< 3 statements and no conditionals)
+ * - Test files (should already be filtered at extraction)
+ * - Type-only files (should already be filtered at extraction)
+ */
+declare function shouldExcludeFunction(fn: ExtractedFunction): boolean;
+/**
+ * Create a fully classified function with all computed properties
+ *
+ * @param fn - The extracted function
+ * @param markers - Detected impurity markers
+ * @param qualityScore - Quality score (null for pure functions)
+ * @param status - Derived status
+ * @returns A fully classified function
+ */
+declare function createClassifiedFunction(fn: ExtractedFunction, markers: ImpurityMarker[], qualityScore: number | null, status: Status): ClassifiedFunction;
+
+/**
+ * Quality Scorer - Pure Core
+ *
+ * Computes quality scores (0-100) for impure functions measuring how
+ * well-structured the impurity is. This is a PURE module - all functions
+ * take data in and return data out with no I/O.
+ *
+ * Quality signals measure structural quality, not whether impurity exists.
+ * A high score means the impure function is well-organized and maintainable.
+ */
+
+/**
+ * Quality scoring weights and thresholds
+ */
+declare const QUALITY_WEIGHTS: {
+    readonly callsPureFile: 30;
+    readonly callsPureNamingConvention: 20;
+    readonly ioConcentratedAtStart: 15;
+    readonly ioConcentratedAtEnd: 15;
+    readonly lowComplexity: 10;
+    readonly shellNamingConvention: 5;
+    readonly callsPredicateFunctions: 5;
+    readonly ioInterleaved: -20;
+    readonly highComplexity: -15;
+    readonly multipleIoTypes: -10;
+    readonly noPureFunctionCalls: -10;
+    readonly veryLongFunction: -10;
+};
+/**
+ * Compute quality score for an impure function
+ *
+ * @param fn - The extracted function data
+ * @param markers - The detected impurity markers
+ * @param context - Detection context with import information
+ * @returns Quality score from 0-100
+ */
+declare function computeQualityScore(fn: ExtractedFunction, markers: ImpurityMarker[], context: DetectionContext): number;
+/**
+ * Analysis result for a function
+ */
+type FunctionAnalysis = {
+    callsPureFile: boolean;
+    callsPureNamingConvention: boolean;
+    ioConcentratedAtStart: boolean;
+    ioConcentratedAtEnd: boolean;
+    lowComplexity: boolean;
+    shellNamingConvention: boolean;
+    callsPredicateFunctions: boolean;
+    ioInterleaved: boolean;
+    highComplexity: boolean;
+    multipleIoTypes: boolean;
+    noPureFunctionCalls: boolean;
+    veryLongFunction: boolean;
+    estimatedComplexity: number;
+    ioMarkerCount: number;
+    uniqueIoTypes: Set<MarkerType>;
+    pureCallCount: number;
+    predicateCallCount: number;
+};
+/**
+ * Analyze a function for quality signals
+ */
+declare function analyzeFunction(fn: ExtractedFunction, markers: ImpurityMarker[], context: DetectionContext): FunctionAnalysis;
+
+/**
+ * Status Derivation - Pure Core
+ *
+ * Derives actionable status from classification and quality score.
+ * This is a PURE module - all functions take data in and return data out with no I/O.
+ *
+ * Status provides developer guidance:
+ * - ok: No action needed (pure function, or well-structured impure function)
+ * - review: Consider improving if touching this code
+ * - refactor: Tangled code, prioritize cleanup
+ */
+
+/**
+ * Derive status from classification and quality score
+ *
+ * Status rules:
+ * - Pure functions always get 'ok' (testable without mocks)
+ * - Impure functions with quality >= okThreshold (default 70) get 'ok'
+ * - Impure functions with quality >= reviewThreshold (default 40) get 'review'
+ * - Impure functions with quality < reviewThreshold get 'refactor'
+ *
+ * @param classification - 'pure' or 'impure'
+ * @param qualityScore - Quality score for impure functions (0-100), null for pure
+ * @param thresholds - Optional custom thresholds
+ * @returns Status: 'ok' | 'review' | 'refactor'
+ */
+declare function deriveStatus(classification: FunctionClassification, qualityScore: number | null, thresholds?: QualityThresholds): Status;
+/**
+ * Get status description for display
+ */
+declare function getStatusDescription(status: Status): string;
+/**
+ * Get status emoji for display
+ */
+declare function getStatusEmoji(status: Status): string;
+/**
+ * Get status color for terminal display
+ */
+declare function getStatusColor(status: Status): 'green' | 'yellow' | 'red';
+
+/**
+ * Scoring Engine - Pure Core
+ *
+ * Aggregates classification and quality scores into metrics at
+ * file, directory, and project levels. This is a PURE module -
+ * all functions take data in and return data out with no I/O.
+ *
+ * Metrics:
+ * - Purity: percentage of pure functions
+ * - Impurity Quality: average quality score of impure functions
+ * - Health: percentage of functions with status 'ok'
+ */
+
+/**
+ * Score a single file based on its classified functions
+ *
+ * @param filePath - Path to the file
+ * @param functions - Classified functions from the file
+ * @param isTypeOnly - Whether the file contains only types
+ * @returns FileScore with all computed metrics
+ */
+declare function scoreFile(filePath: string, functions: ClassifiedFunction[], isTypeOnly?: boolean): FileScore;
+/**
+ * Score a directory by aggregating its file scores
+ *
+ * @param dirPath - Path to the directory
+ * @param fileScores - Scores for all files in the directory
+ * @returns DirectoryScore with weighted averages
+ */
+declare function scoreDirectory(dirPath: string, fileScores: FileScore[]): DirectoryScore;
+/**
+ * Score an entire project by aggregating directory scores
+ *
+ * @param directoryScores - Scores for all directories in the project
+ * @param options - Additional options for the project score
+ * @returns ProjectScore with all metrics
+ */
+declare function scoreProject(directoryScores: DirectoryScore[], options?: {
+    timestamp?: string;
+    commitHash?: string | null;
+    subset?: boolean;
+    filesGlob?: string;
+    errors?: {
+        filePath: string;
+        error: string;
+    }[];
+}): ProjectScore;
+/**
+ * Group file scores by directory
+ *
+ * @param fileScores - Array of file scores
+ * @returns Map of directory path to file scores
+ */
+declare function groupFilesByDirectory(fileScores: FileScore[]): Map<string, FileScore[]>;
+/**
+ * Calculate delta between two project scores
+ *
+ * @param current - Current project score
+ * @param previous - Previous project score
+ * @returns Delta metrics
+ */
+declare function calculateDelta(current: ProjectScore, previous: ProjectScore): {
+    purityDelta: number;
+    impurityQualityDelta: number | null;
+    healthDelta: number;
+    pureCountDelta: number;
+    impureCountDelta: number;
+};
+/**
+ * Get diagnostic insights based on metrics
+ *
+ * @param score - Project or file score
+ * @returns Array of insight messages
+ */
+declare function getDiagnosticInsights(score: Pick<ProjectScore, 'purity' | 'impurityQuality' | 'health'>): string[];
+
+/**
+ * JSON Report Generator - Shell Layer
+ *
+ * Serializes analysis results to JSON format for storage, diffing, and
+ * trend analysis. This is part of the SHELL layer as it produces output.
+ *
+ * The JSON output includes:
+ * - Timestamp and commit hash for versioning
+ * - Full project score with all metrics
+ * - Directory and file breakdowns
+ * - Refactoring candidates
+ * - Any errors encountered during analysis
+ */
+
+/**
+ * JSON report options
+ */
+type JsonReportOptions = {
+    pretty?: boolean;
+    includeFunction?: boolean;
+};
+/**
+ * Generate JSON report string from project score
+ *
+ * @param score - The project score to serialize
+ * @param options - Report options
+ * @returns JSON string representation
+ */
+declare function generateJsonReport(score: ProjectScore, options?: JsonReportOptions): string;
+/**
+ * Write JSON report to file
+ *
+ * @param score - The project score to write
+ * @param outputPath - Path to write the JSON file
+ * @param options - Report options
+ */
+declare function writeJsonReport(score: ProjectScore, outputPath: string, options?: JsonReportOptions): void;
+/**
+ * Read a previous JSON report from file
+ *
+ * @param inputPath - Path to the JSON file
+ * @returns Parsed ProjectScore or null if file doesn't exist
+ */
+declare function readJsonReport(inputPath: string): ProjectScore | null;
+/**
+ * Create a summary JSON suitable for PR comments or CI output
+ *
+ * @param score - The project score
+ * @returns Minimal JSON object with key metrics
+ */
+declare function createSummaryJson(score: ProjectScore): {
+    health: number;
+    purity: number;
+    impurityQuality: number | null;
+    pureCount: number;
+    impureCount: number;
+    statusBreakdown: {
+        ok: number;
+        review: number;
+        refactor: number;
+    };
+    timestamp: string;
+    commitHash: string | null;
+    topRefactoringCandidates: Array<{
+        name: string | null;
+        filePath: string;
+        qualityScore: number;
+    }>;
+};
+/**
+ * Compare two project scores and generate a diff report
+ *
+ * @param current - Current project score
+ * @param previous - Previous project score
+ * @returns JSON object with comparison data
+ */
+declare function generateComparisonReport(current: ProjectScore, previous: ProjectScore): {
+    current: ReturnType<typeof createSummaryJson>;
+    previous: ReturnType<typeof createSummaryJson>;
+    delta: {
+        health: number;
+        purity: number;
+        impurityQuality: number | null;
+        pureCount: number;
+        impureCount: number;
+    };
+    improved: boolean;
+    newRefactoringCandidates: Array<{
+        name: string | null;
+        filePath: string;
+    }>;
+    resolvedRefactoringCandidates: Array<{
+        name: string | null;
+        filePath: string;
+    }>;
+};
+
+/**
+ * Console Report Generator - Shell Layer
+ *
+ * Produces human-readable console output with colors, visual bars,
+ * and formatted tables. This is part of the SHELL layer as it
+ * performs I/O (writing to console).
+ */
+
+/**
+ * Generate and print the full console report
+ */
+declare function printConsoleReport(score: ProjectScore, options?: {
+    verbose?: boolean;
+}): void;
+/**
+ * Generate a single-line summary suitable for CI output
+ */
+declare function generateSummaryLine(score: ProjectScore): string;
+/**
+ * Print a file-level report (for verbose output)
+ */
+declare function printFileReport(fileScore: FileScore): void;
+
+/**
+ * Extractor - Shell layer for loading TypeScript projects via ts-morph
+ *
+ * This module handles the I/O of loading a TypeScript project from disk.
+ * It's a thin shell that delegates to ts-morph for actual parsing.
+ */
+
+type ExtractorOptions = {
+    tsconfigPath: string;
+    filesGlob?: string;
+};
+type ExtractorResult = {
+    project: Project;
+    sourceFiles: SourceFile[];
+    errors: {
+        filePath: string;
+        error: string;
+    }[];
+};
+/**
+ * Loads a TypeScript project from a tsconfig.json path
+ *
+ * @param options - Configuration options for the extractor
+ * @returns The loaded project and source files
+ * @throws Error if tsconfig.json doesn't exist or is invalid
+ */
+declare function loadProject(options: ExtractorOptions): ExtractorResult;
+/**
+ * Gets the commit hash from git if available
+ */
+declare function getCommitHash(): string | null;
+
+/**
+ * AST Function Extraction
+ *
+ * Extracts all function-like nodes from a TypeScript source file into
+ * normalized ExtractedFunction structures. This is part of the SHELL layer
+ * as it interacts with ts-morph AST nodes.
+ *
+ * Handles all function forms:
+ * - FunctionDeclaration
+ * - MethodDeclaration
+ * - ArrowFunction (including those passed as arguments)
+ * - FunctionExpression (including those passed as arguments)
+ * - GetAccessorDeclaration
+ * - SetAccessorDeclaration
+ */
+
+/**
+ * Extract all functions from a source file
+ */
+declare function extractFunctions(sourceFile: SourceFile): ExtractedFunction[];
+/**
+ * Extract imports from a source file
+ */
+declare function extractImports(sourceFile: SourceFile): FileImports;
+/**
+ * Check if a file is type-only (contains only types, interfaces, enums, no function bodies)
+ */
+declare function isTypeOnlyFile(sourceFile: SourceFile): boolean;
+
+export { type AnalysisError, type AnalyzerConfig, type CallSite, type ClassifiedFunction, DEFAULT_QUALITY_THRESHOLDS, type DetectionContext, type DirectoryScore, type ExtractedFunction, type ExtractionResult, type ExtractorOptions, type ExtractorResult, type FileImports, type FileScore, type FunctionAnalysis, type FunctionClassification, type ImpurityMarker, type JsonReportOptions, MARKER_CATALOG, type MarkerDefinition, type MarkerType, type ProjectScore, QUALITY_WEIGHTS, type QualityThresholds, type RefactoringCandidate, type Status, type StatusBreakdown, analyze, analyzeFile, analyzeFilePath, analyzeFunction as analyzeFunctionQuality, calculateDelta, checkThresholds, classifyFunction, computeQualityScore, createClassifiedFunction, createDetectionContext, createSummaryJson, deriveStatus, detectMarkers, extractFunctions, extractImports, generateComparisonReport, generateJsonReport, generateSummaryLine, getAllMarkerTypes, getCommitHash, getDiagnosticInsights, getMarkerDefinition, getPureImportedFunctions, getStatusColor, getStatusDescription, getStatusEmoji, groupFilesByDirectory, isTypeOnlyFile, loadProject, printConsoleReport, printFileReport, readJsonReport, scoreDirectory, scoreFile, scoreProject, shouldExcludeFunction, writeJsonReport };