fcis 0.1.0

package/src/analyzer.ts

@@ -0,0 +1,266 @@
+/**
+ * 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.
+ */
+
+import type { SourceFile } from 'ts-morph'
+
+import type {
+  AnalysisError,
+  AnalyzerConfig,
+  ClassifiedFunction,
+  DirectoryScore,
+  FileScore,
+  ProjectScore,
+} from './types.js'
+import { DEFAULT_QUALITY_THRESHOLDS } from './types.js'
+
+import {
+  extractFunctions,
+  extractImports,
+  isTypeOnlyFile,
+} from './extraction/extract-functions.js'
+import { loadProject, getCommitHash } from './extraction/extractor.js'
+import {
+  detectMarkers,
+  createDetectionContext,
+} from './detection/detect-markers.js'
+import {
+  classifyFunction,
+  shouldExcludeFunction,
+  createClassifiedFunction,
+} from './classification/classifier.js'
+import { computeQualityScore } from './classification/quality-scorer.js'
+import { deriveStatus } from './classification/derive-status.js'
+import {
+  scoreFile,
+  scoreDirectory,
+  scoreProject,
+  groupFilesByDirectory,
+} from './scoring/scorer.js'
+
+/**
+ * Run the full analysis pipeline
+ *
+ * @param config - Analyzer configuration
+ * @returns Project score with all metrics
+ */
+export async function analyze(config: AnalyzerConfig): Promise<ProjectScore> {
+  const errors: AnalysisError[] = []
+
+  // Step 1: Load project
+  const extractorOptions: { tsconfigPath: string; filesGlob?: string } = {
+    tsconfigPath: config.tsconfigPath,
+  }
+  if (config.filesGlob !== undefined) {
+    extractorOptions.filesGlob = config.filesGlob
+  }
+  const { sourceFiles } = loadProject(extractorOptions)
+
+  if (sourceFiles.length === 0) {
+    throw new Error('No source files found to analyze')
+  }
+
+  // Step 2-5: Extract, detect, classify each file
+  const fileScores: FileScore[] = []
+
+  for (const sourceFile of sourceFiles) {
+    try {
+      const fileScore = analyzeFile(sourceFile)
+      fileScores.push(fileScore)
+    } catch (error) {
+      errors.push({
+        filePath: sourceFile.getFilePath(),
+        error: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
+  // Check if any files were successfully analyzed
+  if (fileScores.length === 0 && errors.length > 0) {
+    throw new Error(
+      `Failed to analyze any files. ${errors.length} files had errors.`,
+    )
+  }
+
+  // Step 6: Aggregate into directory scores
+  const directoryGroups = groupFilesByDirectory(fileScores)
+  const directoryScores: DirectoryScore[] = []
+
+  for (const [dirPath, files] of directoryGroups) {
+    const dirScore = scoreDirectory(dirPath, files)
+    directoryScores.push(dirScore)
+  }
+
+  // Sort directories by path for consistent output
+  directoryScores.sort((a, b) => a.dirPath.localeCompare(b.dirPath))
+
+  // Step 7: Aggregate into project score
+  const projectOptions: {
+    timestamp?: string
+    commitHash?: string | null
+    subset?: boolean
+    filesGlob?: string
+    errors?: { filePath: string; error: string }[]
+  } = {
+    timestamp: new Date().toISOString(),
+    commitHash: getCommitHash(),
+  }
+
+  if (config.filesGlob !== undefined) {
+    projectOptions.subset = true
+    projectOptions.filesGlob = config.filesGlob
+  }
+
+  if (errors.length > 0) {
+    projectOptions.errors = errors
+  }
+
+  const projectScore = scoreProject(directoryScores, projectOptions)
+
+  return projectScore
+}
+
+/**
+ * Analyze a single source file
+ *
+ * @param sourceFile - The ts-morph source file to analyze
+ * @returns FileScore with all metrics
+ */
+export function analyzeFile(sourceFile: SourceFile): FileScore {
+  const filePath = sourceFile.getFilePath()
+
+  // Check if type-only file
+  if (isTypeOnlyFile(sourceFile)) {
+    return scoreFile(filePath, [], true)
+  }
+
+  // Extract functions and imports
+  const functions = extractFunctions(sourceFile)
+  const imports = extractImports(sourceFile)
+
+  // Create detection context
+  const context = createDetectionContext(imports)
+
+  // Classify each function
+  const classifiedFunctions: ClassifiedFunction[] = []
+
+  for (const fn of functions) {
+    // Check if function should be excluded
+    if (shouldExcludeFunction(fn)) {
+      continue
+    }
+
+    // Detect markers
+    const markers = detectMarkers(fn, context)
+
+    // Classify
+    const classification = classifyFunction(fn, markers)
+
+    // Compute quality score (only for impure functions)
+    let qualityScore: number | null = null
+    if (classification === 'impure') {
+      qualityScore = computeQualityScore(fn, markers, context)
+    }
+
+    // Derive status
+    const status = deriveStatus(
+      classification,
+      qualityScore,
+      DEFAULT_QUALITY_THRESHOLDS,
+    )
+
+    // Create classified function
+    const classifiedFn = createClassifiedFunction(
+      fn,
+      markers,
+      qualityScore,
+      status,
+    )
+    classifiedFunctions.push(classifiedFn)
+  }
+
+  // Score the file
+  return scoreFile(filePath, classifiedFunctions, false)
+}
+
+/**
+ * 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
+ */
+export async function analyzeFilePath(
+  tsconfigPath: string,
+  filePath: string,
+): Promise<FileScore | null> {
+  const { sourceFiles } = loadProject({
+    tsconfigPath,
+    filesGlob: filePath,
+  })
+
+  if (sourceFiles.length === 0) {
+    return null
+  }
+
+  const sourceFile = sourceFiles[0]
+  if (!sourceFile) {
+    return null
+  }
+
+  return analyzeFile(sourceFile)
+}
+
+/**
+ * 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
+ */
+export function checkThresholds(
+  score: ProjectScore,
+  config: Pick<AnalyzerConfig, 'minHealth' | 'minPurity' | 'minQuality'>,
+): {
+  passed: boolean
+  failures: string[]
+} {
+  const failures: string[] = []
+
+  if (config.minHealth !== undefined && score.health < config.minHealth) {
+    failures.push(
+      `Health ${score.health.toFixed(1)}% is below minimum ${config.minHealth}%`,
+    )
+  }
+
+  if (config.minPurity !== undefined && score.purity < config.minPurity) {
+    failures.push(
+      `Purity ${score.purity.toFixed(1)}% is below minimum ${config.minPurity}%`,
+    )
+  }
+
+  if (
+    config.minQuality !== undefined &&
+    score.impurityQuality !== null &&
+    score.impurityQuality < config.minQuality
+  ) {
+    failures.push(
+      `Impurity Quality ${score.impurityQuality.toFixed(1)}% is below minimum ${config.minQuality}%`,
+    )
+  }
+
+  return {
+    passed: failures.length === 0,
+    failures,
+  }
+}

package/src/classification/classifier.ts

@@ -0,0 +1,156 @@
+/**
+ * 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.
+ */
+
+import type {
+  ClassifiedFunction,
+  ExtractedFunction,
+  FunctionClassification,
+  ImpurityMarker,
+  Status,
+} from '../types.js'
+
+/**
+ * Minimum statements for a function to be considered for scoring
+ * Functions with fewer statements are considered trivial
+ */
+const TRIVIAL_STATEMENT_THRESHOLD = 3
+
+/**
+ * Classify a function based on its markers
+ *
+ * @param fn - The extracted function
+ * @param markers - Detected impurity markers
+ * @returns The function classification ('pure' or 'impure')
+ */
+export function classifyFunction(
+  _fn: ExtractedFunction,
+  markers: ImpurityMarker[],
+): FunctionClassification {
+  // A function is pure if it has no impurity markers
+  if (markers.length === 0) {
+    return 'pure'
+  }
+
+  return 'impure'
+}
+
+/**
+ * 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)
+ */
+export function shouldExcludeFunction(fn: ExtractedFunction): boolean {
+  // Exclude trivial functions: less than threshold statements and no conditionals
+  if (fn.statementCount < TRIVIAL_STATEMENT_THRESHOLD && !fn.hasConditionals) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * 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
+ */
+export function createClassifiedFunction(
+  fn: ExtractedFunction,
+  markers: ImpurityMarker[],
+  qualityScore: number | null,
+  status: Status,
+): ClassifiedFunction {
+  const classification = classifyFunction(fn, markers)
+
+  return {
+    ...fn,
+    markers,
+    classification,
+    qualityScore,
+    status,
+  }
+}
+
+/**
+ * Batch classify multiple functions
+ *
+ * @param functions - Array of extracted functions with their markers
+ * @returns Array of classified functions
+ */
+export function classifyFunctions(
+  functions: Array<{
+    fn: ExtractedFunction
+    markers: ImpurityMarker[]
+    qualityScore: number | null
+    status: Status
+  }>,
+): ClassifiedFunction[] {
+  return functions.map(({ fn, markers, qualityScore, status }) =>
+    createClassifiedFunction(fn, markers, qualityScore, status),
+  )
+}
+
+/**
+ * Partition functions into pure and impure
+ *
+ * @param functions - Array of classified functions
+ * @returns Object with pure and impure function arrays
+ */
+export function partitionByClassification(functions: ClassifiedFunction[]): {
+  pure: ClassifiedFunction[]
+  impure: ClassifiedFunction[]
+} {
+  const pure: ClassifiedFunction[] = []
+  const impure: ClassifiedFunction[] = []
+
+  for (const fn of functions) {
+    if (fn.classification === 'pure') {
+      pure.push(fn)
+    } else {
+      impure.push(fn)
+    }
+  }
+
+  return { pure, impure }
+}
+
+/**
+ * Get classification summary for a set of functions
+ *
+ * @param functions - Array of classified functions
+ * @returns Summary statistics
+ */
+export function getClassificationSummary(functions: ClassifiedFunction[]): {
+  total: number
+  pureCount: number
+  impureCount: number
+  purityPercentage: number
+} {
+  const total = functions.length
+  const pureCount = functions.filter(f => f.classification === 'pure').length
+  const impureCount = total - pureCount
+  const purityPercentage = total > 0 ? (pureCount / total) * 100 : 100
+
+  return {
+    total,
+    pureCount,
+    impureCount,
+    purityPercentage,
+  }
+}

package/src/classification/derive-status.ts

@@ -0,0 +1,171 @@
+/**
+ * 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
+ */
+
+import type {
+  ClassifiedFunction,
+  FunctionClassification,
+  QualityThresholds,
+  Status,
+} from '../types.js'
+import { DEFAULT_QUALITY_THRESHOLDS } from '../types.js'
+
+/**
+ * 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'
+ */
+export function deriveStatus(
+  classification: FunctionClassification,
+  qualityScore: number | null,
+  thresholds: QualityThresholds = DEFAULT_QUALITY_THRESHOLDS,
+): Status {
+  // Pure functions are always ok - testable without mocks
+  if (classification === 'pure') {
+    return 'ok'
+  }
+
+  // Impure functions need quality score evaluation
+  if (qualityScore === null) {
+    // This shouldn't happen for impure functions, but handle defensively
+    return 'review'
+  }
+
+  if (qualityScore >= thresholds.okThreshold) {
+    return 'ok'
+  }
+
+  if (qualityScore >= thresholds.reviewThreshold) {
+    return 'review'
+  }
+
+  return 'refactor'
+}
+
+/**
+ * Get status description for display
+ */
+export function getStatusDescription(status: Status): string {
+  switch (status) {
+    case 'ok':
+      return 'No action needed'
+    case 'review':
+      return 'Consider improving if touching this code'
+    case 'refactor':
+      return 'Tangled code, prioritize cleanup'
+  }
+}
+
+/**
+ * Get status emoji for display
+ */
+export function getStatusEmoji(status: Status): string {
+  switch (status) {
+    case 'ok':
+      return '✓'
+    case 'review':
+      return '◐'
+    case 'refactor':
+      return '✗'
+  }
+}
+
+/**
+ * Get status color for terminal display
+ */
+export function getStatusColor(status: Status): 'green' | 'yellow' | 'red' {
+  switch (status) {
+    case 'ok':
+      return 'green'
+    case 'review':
+      return 'yellow'
+    case 'refactor':
+      return 'red'
+  }
+}
+
+/**
+ * Check if a classified function should be flagged for attention
+ * (status is 'review' or 'refactor')
+ */
+export function needsAttention(fn: ClassifiedFunction): boolean {
+  return fn.status === 'review' || fn.status === 'refactor'
+}
+
+/**
+ * Check if a classified function is in good standing
+ * (status is 'ok')
+ */
+export function isOk(fn: ClassifiedFunction): boolean {
+  return fn.status === 'ok'
+}
+
+/**
+ * Sort functions by status priority (refactor first, then review, then ok)
+ */
+export function sortByStatusPriority(
+  functions: ClassifiedFunction[],
+): ClassifiedFunction[] {
+  const priorityMap: Record<Status, number> = {
+    refactor: 0,
+    review: 1,
+    ok: 2,
+  }
+
+  return [...functions].sort((a, b) => {
+    const priorityDiff = priorityMap[a.status] - priorityMap[b.status]
+    if (priorityDiff !== 0) return priorityDiff
+
+    // Secondary sort by quality score (lower first for impure functions)
+    if (a.qualityScore !== null && b.qualityScore !== null) {
+      return a.qualityScore - b.qualityScore
+    }
+
+    // Tertiary sort by body line count (larger first)
+    return b.bodyLineCount - a.bodyLineCount
+  })
+}
+
+/**
+ * Validate threshold configuration
+ */
+export function validateThresholds(thresholds: QualityThresholds): {
+  valid: boolean
+  errors: string[]
+} {
+  const errors: string[] = []
+
+  if (thresholds.okThreshold < 0 || thresholds.okThreshold > 100) {
+    errors.push('okThreshold must be between 0 and 100')
+  }
+
+  if (thresholds.reviewThreshold < 0 || thresholds.reviewThreshold > 100) {
+    errors.push('reviewThreshold must be between 0 and 100')
+  }
+
+  if (thresholds.reviewThreshold >= thresholds.okThreshold) {
+    errors.push('reviewThreshold must be less than okThreshold')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}