fcis 0.1.0

package/src/classification/quality-scorer.ts

@@ -0,0 +1,481 @@
+/**
+ * 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.
+ */
+
+import type {
+  CallSite,
+  DetectionContext,
+  ExtractedFunction,
+  ImpurityMarker,
+  MarkerType,
+} from '../types.js'
+
+/**
+ * Quality scoring weights and thresholds
+ */
+export const QUALITY_WEIGHTS = {
+  // Positive signals (additive)
+  callsPureFile: 30, // Calls a function from .pure.ts file
+  callsPureNamingConvention: 20, // Calls plan*/derive*/compute*/calculate*/transform*
+  ioConcentratedAtStart: 15, // I/O calls concentrated at start (GATHER pattern)
+  ioConcentratedAtEnd: 15, // I/O calls concentrated at end (EXECUTE pattern)
+  lowComplexity: 10, // Low cyclomatic complexity (≤ 5)
+  shellNamingConvention: 5, // Function name matches shell conventions
+  callsPredicateFunctions: 5, // Calls is*/has*/should* functions
+
+  // Negative signals (penalties)
+  ioInterleaved: -20, // I/O calls interleaved throughout
+  highComplexity: -15, // High cyclomatic complexity (> 10)
+  multipleIoTypes: -10, // Multiple I/O types in same function
+  noPureFunctionCalls: -10, // No pure function calls at all
+  veryLongFunction: -10, // > 100 lines
+} as const
+
+/**
+ * Pure function naming patterns
+ */
+const PURE_FUNCTION_PATTERNS = [
+  /^plan[A-Z]/,
+  /^derive[A-Z]/,
+  /^compute[A-Z]/,
+  /^calculate[A-Z]/,
+  /^transform[A-Z]/,
+  /^build[A-Z]/,
+  /^create[A-Z](?!.*Service)/, // createX but not createXService
+  /^parse[A-Z]/,
+  /^format[A-Z]/,
+  /^validate[A-Z]/,
+  /^normalize[A-Z]/,
+  /^convert[A-Z]/,
+  /^map[A-Z]/,
+  /^filter[A-Z]/,
+  /^reduce[A-Z]/,
+  /^merge[A-Z]/,
+  /^extract[A-Z]/,
+  /^to[A-Z]/, // toPublicX, toDTO, etc.
+]
+
+/**
+ * Predicate function patterns (return boolean)
+ */
+const PREDICATE_PATTERNS = [
+  /^is[A-Z]/,
+  /^has[A-Z]/,
+  /^should[A-Z]/,
+  /^can[A-Z]/,
+  /^will[A-Z]/,
+  /^was[A-Z]/,
+  /^did[A-Z]/,
+  /^are[A-Z]/,
+  /^does[A-Z]/,
+  /^needs[A-Z]/,
+]
+
+/**
+ * Shell function naming patterns
+ */
+const SHELL_FUNCTION_PATTERNS = [
+  /^handle[A-Z]/,
+  /^fetch[A-Z]/,
+  /^save[A-Z]/,
+  /^send[A-Z]/,
+  /^load[A-Z]/,
+  /^get[A-Z]/, // getData, getUser, etc.
+  /^set[A-Z]/,
+  /^update[A-Z]/,
+  /^delete[A-Z]/,
+  /^remove[A-Z]/,
+  /^create[A-Z].*Service/, // createXService
+  /^init[A-Z]/,
+  /^process[A-Z]/,
+  /^execute[A-Z]/,
+  /^run[A-Z]/,
+  /^perform[A-Z]/,
+]
+
+/**
+ * I/O marker types for concentration analysis
+ */
+const IO_MARKER_TYPES: Set<MarkerType> = new Set([
+  'await-expression',
+  'database-call',
+  'network-fetch',
+  'network-http',
+  'fs-call',
+])
+
+/**
+ * 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
+ */
+export function computeQualityScore(
+  fn: ExtractedFunction,
+  markers: ImpurityMarker[],
+  context: DetectionContext,
+): number {
+  let score = 50 // Start at neutral
+
+  // Analyze the function and accumulate score adjustments
+  const analysis = analyzeFunction(fn, markers, context)
+
+  // Apply positive signals
+  if (analysis.callsPureFile) {
+    score += QUALITY_WEIGHTS.callsPureFile
+  }
+  if (analysis.callsPureNamingConvention) {
+    score += QUALITY_WEIGHTS.callsPureNamingConvention
+  }
+  if (analysis.ioConcentratedAtStart) {
+    score += QUALITY_WEIGHTS.ioConcentratedAtStart
+  }
+  if (analysis.ioConcentratedAtEnd) {
+    score += QUALITY_WEIGHTS.ioConcentratedAtEnd
+  }
+  if (analysis.lowComplexity) {
+    score += QUALITY_WEIGHTS.lowComplexity
+  }
+  if (analysis.shellNamingConvention) {
+    score += QUALITY_WEIGHTS.shellNamingConvention
+  }
+  if (analysis.callsPredicateFunctions) {
+    score += QUALITY_WEIGHTS.callsPredicateFunctions
+  }
+
+  // Apply negative signals (penalties)
+  if (analysis.ioInterleaved) {
+    score += QUALITY_WEIGHTS.ioInterleaved
+  }
+  if (analysis.highComplexity) {
+    score += QUALITY_WEIGHTS.highComplexity
+  }
+  if (analysis.multipleIoTypes) {
+    score += QUALITY_WEIGHTS.multipleIoTypes
+  }
+  if (analysis.noPureFunctionCalls) {
+    score += QUALITY_WEIGHTS.noPureFunctionCalls
+  }
+  if (analysis.veryLongFunction) {
+    score += QUALITY_WEIGHTS.veryLongFunction
+  }
+
+  // Clamp score to 0-100
+  return Math.max(0, Math.min(100, score))
+}
+
+/**
+ * Analysis result for a function
+ */
+export type FunctionAnalysis = {
+  // Positive signals
+  callsPureFile: boolean
+  callsPureNamingConvention: boolean
+  ioConcentratedAtStart: boolean
+  ioConcentratedAtEnd: boolean
+  lowComplexity: boolean
+  shellNamingConvention: boolean
+  callsPredicateFunctions: boolean
+
+  // Negative signals
+  ioInterleaved: boolean
+  highComplexity: boolean
+  multipleIoTypes: boolean
+  noPureFunctionCalls: boolean
+  veryLongFunction: boolean
+
+  // Metrics
+  estimatedComplexity: number
+  ioMarkerCount: number
+  uniqueIoTypes: Set<MarkerType>
+  pureCallCount: number
+  predicateCallCount: number
+}
+
+/**
+ * Analyze a function for quality signals
+ */
+export function analyzeFunction(
+  fn: ExtractedFunction,
+  markers: ImpurityMarker[],
+  context: DetectionContext,
+): FunctionAnalysis {
+  // Get I/O markers with line information
+  const ioMarkers = markers.filter(
+    m => IO_MARKER_TYPES.has(m.type) && m.line !== undefined,
+  )
+
+  // Unique I/O types
+  const uniqueIoTypes = new Set(markers.map(m => m.type))
+
+  // Check for pure file imports being called
+  const callsPureFile = checkCallsPureFile(fn, context)
+
+  // Check for pure naming convention calls
+  const { callsPureNaming, pureCallCount } = checkCallsPureNamingConvention(
+    fn.callSites,
+  )
+
+  // Check for predicate function calls
+  const { callsPredicates, predicateCallCount } = checkCallsPredicateFunctions(
+    fn.callSites,
+  )
+
+  // Check I/O concentration
+  const { concentratedAtStart, concentratedAtEnd, interleaved } =
+    analyzeIoConcentration(fn, ioMarkers)
+
+  // Estimate complexity
+  const estimatedComplexity = estimateCyclomaticComplexity(fn)
+
+  // Check shell naming convention
+  const shellNamingConvention = checkShellNamingConvention(fn.name)
+
+  return {
+    callsPureFile,
+    callsPureNamingConvention: callsPureNaming,
+    ioConcentratedAtStart: concentratedAtStart,
+    ioConcentratedAtEnd: concentratedAtEnd,
+    lowComplexity: estimatedComplexity <= 5,
+    shellNamingConvention,
+    callsPredicateFunctions: callsPredicates,
+
+    ioInterleaved: interleaved,
+    highComplexity: estimatedComplexity > 10,
+    multipleIoTypes: uniqueIoTypes.size >= 3,
+    noPureFunctionCalls: pureCallCount === 0 && predicateCallCount === 0,
+    veryLongFunction: fn.bodyLineCount > 100,
+
+    estimatedComplexity,
+    ioMarkerCount: ioMarkers.length,
+    uniqueIoTypes,
+    pureCallCount,
+    predicateCallCount,
+  }
+}
+
+/**
+ * Check if function calls any imports from .pure files
+ */
+function checkCallsPureFile(
+  fn: ExtractedFunction,
+  context: DetectionContext,
+): boolean {
+  // Get names of functions imported from .pure files
+  const pureImports = new Set<string>()
+  for (const imp of context.imports.imports) {
+    if (context.pureFileImports.has(imp.moduleSpecifier)) {
+      for (const name of imp.namedImports) {
+        pureImports.add(name)
+      }
+    }
+  }
+
+  // Check if any call site calls a pure import
+  for (const callSite of fn.callSites) {
+    const calledFn = extractFunctionName(callSite.expression)
+    if (pureImports.has(calledFn)) {
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if function calls functions with pure naming conventions
+ */
+function checkCallsPureNamingConvention(callSites: CallSite[]): {
+  callsPureNaming: boolean
+  pureCallCount: number
+} {
+  let pureCallCount = 0
+
+  for (const callSite of callSites) {
+    const calledFn = extractFunctionName(callSite.expression)
+    if (matchesAnyPattern(calledFn, PURE_FUNCTION_PATTERNS)) {
+      pureCallCount++
+    }
+  }
+
+  return {
+    callsPureNaming: pureCallCount > 0,
+    pureCallCount,
+  }
+}
+
+/**
+ * Check if function calls predicate functions
+ */
+function checkCallsPredicateFunctions(callSites: CallSite[]): {
+  callsPredicates: boolean
+  predicateCallCount: number
+} {
+  let predicateCallCount = 0
+
+  for (const callSite of callSites) {
+    const calledFn = extractFunctionName(callSite.expression)
+    if (matchesAnyPattern(calledFn, PREDICATE_PATTERNS)) {
+      predicateCallCount++
+    }
+  }
+
+  return {
+    callsPredicates: predicateCallCount > 0,
+    predicateCallCount,
+  }
+}
+
+/**
+ * Analyze I/O concentration within a function
+ *
+ * Good FCIS patterns:
+ * - GATHER: I/O at the start, then pure logic
+ * - EXECUTE: Pure logic, then I/O at the end
+ * - GATHER-DECIDE-EXECUTE: I/O at start, pure in middle, I/O at end
+ *
+ * Bad pattern:
+ * - Interleaved: I/O calls scattered throughout
+ */
+function analyzeIoConcentration(
+  fn: ExtractedFunction,
+  ioMarkers: ImpurityMarker[],
+): {
+  concentratedAtStart: boolean
+  concentratedAtEnd: boolean
+  interleaved: boolean
+} {
+  if (ioMarkers.length === 0) {
+    return {
+      concentratedAtStart: false,
+      concentratedAtEnd: false,
+      interleaved: false,
+    }
+  }
+
+  // Get I/O positions as percentages through the function
+  const positions = ioMarkers
+    .map(m => (m.line ?? 0) / Math.max(fn.bodyLineCount, 1))
+    .sort((a, b) => a - b)
+
+  // Calculate concentration metrics
+  const startThreshold = 0.33 // First third
+  const endThreshold = 0.67 // Last third
+
+  const atStart = positions.filter(p => p <= startThreshold).length
+  const atEnd = positions.filter(p => p >= endThreshold).length
+  const inMiddle = positions.filter(
+    p => p > startThreshold && p < endThreshold,
+  ).length
+
+  const total = positions.length
+
+  // Concentrated at start: most I/O in first third
+  const concentratedAtStart = atStart >= total * 0.6 && inMiddle <= 1
+
+  // Concentrated at end: most I/O in last third
+  const concentratedAtEnd = atEnd >= total * 0.6 && inMiddle <= 1
+
+  // Interleaved: I/O scattered throughout
+  // Consider it interleaved if there's significant I/O in all sections
+  // or if there are many transitions between I/O and non-I/O regions
+  const interleaved =
+    inMiddle >= 2 ||
+    (atStart > 0 && atEnd > 0 && inMiddle > 0) ||
+    (total >= 4 && !concentratedAtStart && !concentratedAtEnd)
+
+  return {
+    concentratedAtStart,
+    concentratedAtEnd,
+    interleaved,
+  }
+}
+
+/**
+ * Estimate cyclomatic complexity from extracted function data
+ *
+ * Cyclomatic complexity = 1 + number of decision points
+ * Since we don't have full AST access here, we estimate based on:
+ * - hasConditionals flag
+ * - statement count
+ * - body line count
+ */
+function estimateCyclomaticComplexity(fn: ExtractedFunction): number {
+  let complexity = 1 // Base complexity
+
+  // If has conditionals, estimate based on statement density
+  if (fn.hasConditionals) {
+    // Rough estimate: conditionals add 1-2 per ~10 statements
+    complexity += Math.ceil(fn.statementCount / 10)
+  }
+
+  // Factor in line count for very long functions
+  if (fn.bodyLineCount > 50) {
+    complexity += Math.floor((fn.bodyLineCount - 50) / 25)
+  }
+
+  return complexity
+}
+
+/**
+ * Check if function name matches shell naming conventions
+ */
+function checkShellNamingConvention(name: string | null): boolean {
+  if (!name) return false
+  return matchesAnyPattern(name, SHELL_FUNCTION_PATTERNS)
+}
+
+/**
+ * Extract the function name from a call expression
+ * e.g., "db.user.findFirst" -> "findFirst"
+ *       "planAcceptInvite" -> "planAcceptInvite"
+ *       "this.validate" -> "validate"
+ */
+function extractFunctionName(expression: string): string {
+  const parts = expression.split('.')
+  return parts[parts.length - 1] ?? expression
+}
+
+/**
+ * Check if a string matches any of the given patterns
+ */
+function matchesAnyPattern(str: string, patterns: RegExp[]): boolean {
+  return patterns.some(pattern => pattern.test(str))
+}
+
+/**
+ * Get quality score interpretation
+ */
+export function interpretQualityScore(score: number): {
+  level: 'high' | 'medium' | 'low'
+  description: string
+} {
+  if (score >= 70) {
+    return {
+      level: 'high',
+      description:
+        'Well-structured impure function. I/O is organized and pure logic is separated.',
+    }
+  } else if (score >= 40) {
+    return {
+      level: 'medium',
+      description:
+        'Moderately structured. Could benefit from extracting pure logic.',
+    }
+  } else {
+    return {
+      level: 'low',
+      description:
+        'Tangled structure. Business logic mixed with I/O. Consider refactoring.',
+    }
+  }
+}