fcis 0.1.0 → 0.2.0

package/src/scoring/scorer.ts

@@ -6,9 +6,14 @@
  * all functions take data in and return data out with no I/O.
  *
  * Metrics:
- * - Purity: percentage of pure functions
+ * - Purity: percentage of pure functions (top-level only, excluding inline callbacks)
  * - Impurity Quality: average quality score of impure functions
  * - Health: percentage of functions with status 'ok'
+ *
+ * Compositional Scoring (Plan 007):
+ * - Inline callbacks are absorbed into their parent function's score
+ * - Function counts only include top-level functions
+ * - Line counts don't double-count (parent bodyLineCount includes nested callbacks)
  */
 
 import type {
@@ -20,6 +25,250 @@ import type {
   StatusBreakdown,
 } from '../types.js'
 
+// ============================================================================
+// Compositional Scoring Helpers
+// ============================================================================
+
+/**
+ * Represents a function with its absorbed inline callbacks
+ */
+type FunctionWithChildren = {
+  fn: ClassifiedFunction
+  children: ClassifiedFunction[]
+}
+
+/**
+ * Group functions by their parent, building a tree structure.
+ * Top-level functions (isInlineCallback=false OR enclosingFunctionStartLine=null)
+ * become roots; inline callbacks become children of their enclosing function.
+ *
+ * @param functions - All classified functions in a file
+ * @returns Array of top-level functions with their children
+ */
+export function groupFunctionsByParent(
+  functions: ClassifiedFunction[],
+): FunctionWithChildren[] {
+  // Build a map of startLine -> function for quick lookup
+  const byStartLine = new Map<number, ClassifiedFunction>()
+  for (const fn of functions) {
+    byStartLine.set(fn.startLine, fn)
+  }
+
+  // Separate top-level functions from inline callbacks with enclosing functions
+  const topLevel: FunctionWithChildren[] = []
+  const childrenByParentLine = new Map<number, ClassifiedFunction[]>()
+
+  for (const fn of functions) {
+    // A function is top-level if:
+    // 1. It's not an inline callback, OR
+    // 2. It's an inline callback but at module scope (no enclosing function)
+    const isTopLevel =
+      !fn.isInlineCallback || fn.enclosingFunctionStartLine === null
+
+    if (isTopLevel) {
+      topLevel.push({ fn, children: [] })
+    } else if (fn.enclosingFunctionStartLine !== null) {
+      // This is an inline callback with an enclosing function
+      const existing = childrenByParentLine.get(fn.enclosingFunctionStartLine)
+      if (existing) {
+        existing.push(fn)
+      } else {
+        childrenByParentLine.set(fn.enclosingFunctionStartLine, [fn])
+      }
+    }
+  }
+
+  // Attach children to their parents
+  for (const entry of topLevel) {
+    const children = childrenByParentLine.get(entry.fn.startLine)
+    if (children) {
+      entry.children = children
+    }
+  }
+
+  return topLevel
+}
+
+/**
+ * Check if a function or any of its children is impure
+ */
+function isEffectivelyImpure(entry: FunctionWithChildren): boolean {
+  if (entry.fn.classification === 'impure') return true
+  return entry.children.some(child => child.classification === 'impure')
+}
+
+/**
+ * Get the effective status for a function considering its children.
+ * The worst status among the function and its children wins.
+ */
+function getEffectiveStatus(
+  entry: FunctionWithChildren,
+): 'ok' | 'review' | 'refactor' {
+  const statuses = [entry.fn.status, ...entry.children.map(c => c.status)]
+
+  if (statuses.includes('refactor')) return 'refactor'
+  if (statuses.includes('review')) return 'review'
+  return 'ok'
+}
+
+/**
+ * Compute the blended quality score for a function with children.
+ * Uses line-count-weighted average of parent and impure children.
+ *
+ * Formula:
+ *   composedQuality = (parentQuality × parentOwnLines + Σ(childQuality × childLines)) / totalLines
+ *
+ * Where parentOwnLines = parent.bodyLineCount - Σ(child.bodyLineCount), clamped to min 1
+ *
+ * If all children are pure, returns the parent's quality unchanged.
+ * If parent is pure but has impure children, returns weighted avg of children only.
+ */
+function computeComposedQuality(entry: FunctionWithChildren): number {
+  const impureChildren = entry.children.filter(
+    c => c.classification === 'impure',
+  )
+
+  // If no impure children, use parent's quality (or default if parent is pure)
+  if (impureChildren.length === 0) {
+    return entry.fn.qualityScore ?? 50
+  }
+
+  // Calculate child line counts
+  const childTotalLines = entry.children.reduce(
+    (sum, c) => sum + c.bodyLineCount,
+    0,
+  )
+
+  // Parent's own lines (excluding nested callbacks), clamped to at least 1
+  const parentOwnLines = Math.max(1, entry.fn.bodyLineCount - childTotalLines)
+
+  // Total lines for weighting
+  const totalLines = parentOwnLines + childTotalLines
+
+  // Parent's quality contribution (use 50 as default if pure parent with impure children)
+  const parentQuality = entry.fn.qualityScore ?? 50
+  const parentContribution = parentQuality * parentOwnLines
+
+  // Children's quality contribution (only impure children affect impurity quality)
+  const childContribution = impureChildren.reduce(
+    (sum, c) => sum + (c.qualityScore ?? 50) * c.bodyLineCount,
+    0,
+  )
+
+  // Weighted blend
+  return (parentContribution + childContribution) / totalLines
+}
+
+/**
+ * Common shape for items that can be aggregated
+ */
+type Aggregatable = {
+  pureCount: number
+  impureCount: number
+  impurityQuality: number | null
+  statusBreakdown: StatusBreakdown
+  pureLineCount: number
+  impureLineCount: number
+  excludedCount: number
+}
+
+/**
+ * Result of aggregating metrics from multiple items
+ */
+type AggregatedMetrics = {
+  purity: number
+  impurityQuality: number | null
+  health: number
+  pureCount: number
+  impureCount: number
+  excludedCount: number
+  statusBreakdown: StatusBreakdown
+  pureLineCount: number
+  impureLineCount: number
+}
+
+/**
+ * Aggregate metrics from multiple items using weighted averages
+ *
+ * @param items - Array of items with metric counts
+ * @returns Aggregated metrics with weighted averages
+ */
+export function aggregateMetrics<T extends Aggregatable>(
+  items: T[],
+): AggregatedMetrics {
+  // Filter to items with actual functions
+  const scorableItems = items.filter(
+    item => item.pureCount + item.impureCount > 0,
+  )
+
+  // Calculate totals
+  const totalPure = items.reduce((sum, item) => sum + item.pureCount, 0)
+  const totalImpure = items.reduce((sum, item) => sum + item.impureCount, 0)
+  const total = totalPure + totalImpure
+
+  // Handle empty case
+  if (total === 0) {
+    return {
+      purity: 100,
+      impurityQuality: null,
+      health: 100,
+      pureCount: 0,
+      impureCount: 0,
+      excludedCount: items.reduce((sum, item) => sum + item.excludedCount, 0),
+      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
+      pureLineCount: 0,
+      impureLineCount: 0,
+    }
+  }
+
+  // Weighted purity by function count
+  const purity = (totalPure / total) * 100
+
+  // Weighted impurity quality
+  let impurityQuality: number | null = null
+  if (totalImpure > 0) {
+    const weightedQuality = scorableItems.reduce((sum, item) => {
+      if (item.impurityQuality !== null && item.impureCount > 0) {
+        return sum + item.impurityQuality * item.impureCount
+      }
+      return sum
+    }, 0)
+    impurityQuality = weightedQuality / totalImpure
+  }
+
+  // Aggregate status breakdown
+  const statusBreakdown: StatusBreakdown = {
+    ok: items.reduce((sum, item) => sum + item.statusBreakdown.ok, 0),
+    review: items.reduce((sum, item) => sum + item.statusBreakdown.review, 0),
+    refactor: items.reduce(
+      (sum, item) => sum + item.statusBreakdown.refactor,
+      0,
+    ),
+  }
+
+  // Calculate health (percentage with status 'ok')
+  const health = (statusBreakdown.ok / total) * 100
+
+  // Aggregate line counts
+  const pureLineCount = items.reduce((sum, item) => sum + item.pureLineCount, 0)
+  const impureLineCount = items.reduce(
+    (sum, item) => sum + item.impureLineCount,
+    0,
+  )
+
+  return {
+    purity,
+    impurityQuality,
+    health,
+    pureCount: totalPure,
+    impureCount: totalImpure,
+    excludedCount: items.reduce((sum, item) => sum + item.excludedCount, 0),
+    statusBreakdown,
+    pureLineCount,
+    impureLineCount,
+  }
+}
+
 /**
  * Score a single file based on its classified functions
  *
@@ -52,16 +301,11 @@ export function scoreFile(
     }
   }
 
-  // Partition functions by classification
-  const pureFunctions = functions.filter(f => f.classification === 'pure')
-  const impureFunctions = functions.filter(f => f.classification === 'impure')
-
-  const pureCount = pureFunctions.length
-  const impureCount = impureFunctions.length
-  const total = pureCount + impureCount
+  // Group functions by parent for compositional scoring
+  const grouped = groupFunctionsByParent(functions)
 
   // Handle empty files
-  if (total === 0) {
+  if (grouped.length === 0) {
     return {
       filePath,
       purity: 100,
@@ -79,50 +323,72 @@ export function scoreFile(
     }
   }
 
-  // Calculate purity (percentage of pure functions)
-  const purity = (pureCount / total) * 100
+  // Count top-level functions by effective classification
+  // A function is effectively impure if it or any of its children is impure
+  let pureCount = 0
+  let impureCount = 0
+  let pureLineCount = 0
+  let impureLineCount = 0
+  const statusBreakdown: StatusBreakdown = { ok: 0, review: 0, refactor: 0 }
+
+  for (const entry of grouped) {
+    const effectivelyImpure = isEffectivelyImpure(entry)
+    const effectiveStatus = getEffectiveStatus(entry)
+
+    if (effectivelyImpure) {
+      impureCount++
+      // Use parent's bodyLineCount (already includes children)
+      impureLineCount += entry.fn.bodyLineCount
+    } else {
+      pureCount++
+      pureLineCount += entry.fn.bodyLineCount
+    }
+
+    statusBreakdown[effectiveStatus]++
+  }
+
+  const total = pureCount + impureCount
+
+  // Calculate purity (percentage of effectively pure top-level functions)
+  const purity = total > 0 ? (pureCount / total) * 100 : 100
 
-  // Calculate impurity quality (average quality of impure functions)
+  // Calculate impurity quality using composed quality scores
+  // Each effectively impure function's quality is blended with its impure children
   let impurityQuality: number | null = null
   if (impureCount > 0) {
-    const totalQuality = impureFunctions.reduce(
-      (sum, f) => sum + (f.qualityScore ?? 0),
+    const impureEntries = grouped.filter(e => isEffectivelyImpure(e))
+    const totalQuality = impureEntries.reduce(
+      (sum, e) => sum + computeComposedQuality(e),
       0,
     )
     impurityQuality = totalQuality / impureCount
   }
 
-  // Calculate status breakdown
-  const statusBreakdown: StatusBreakdown = {
-    ok: functions.filter(f => f.status === 'ok').length,
-    review: functions.filter(f => f.status === 'review').length,
-    refactor: functions.filter(f => f.status === 'refactor').length,
-  }
-
-  // Calculate health (percentage with status 'ok')
-  const health = (statusBreakdown.ok / total) * 100
-
-  // Calculate line counts
-  const pureLineCount = pureFunctions.reduce(
-    (sum, f) => sum + f.bodyLineCount,
-    0,
-  )
-  const impureLineCount = impureFunctions.reduce(
-    (sum, f) => sum + f.bodyLineCount,
-    0,
-  )
+  // Calculate health (percentage with effective status 'ok')
+  const health = total > 0 ? (statusBreakdown.ok / total) * 100 : 100
 
-  // Get refactoring candidates (functions with status 'refactor')
+  // Get refactoring candidates from effectively impure top-level functions
   // Sorted by impact: bodyLineCount × (100 - qualityScore) descending
-  const refactoringCandidates = impureFunctions
-    .filter(f => f.status === 'refactor')
-    .map(f => ({
-      name: f.name,
-      startLine: f.startLine,
-      bodyLineCount: f.bodyLineCount,
-      qualityScore: f.qualityScore ?? 0,
-      markers: f.markers.map(m => m.type),
-    }))
+  // Markers are aggregated from parent AND children for comprehensive reporting
+  const refactoringCandidates = grouped
+    .filter(e => isEffectivelyImpure(e) && getEffectiveStatus(e) === 'refactor')
+    .map(e => {
+      // Aggregate markers from parent and all children
+      const allMarkers = [
+        ...e.fn.markers.map(m => m.type),
+        ...e.children.flatMap(c => c.markers.map(m => m.type)),
+      ]
+      // Dedupe markers (same type from multiple children)
+      const uniqueMarkers = [...new Set(allMarkers)]
+
+      return {
+        name: e.fn.name,
+        startLine: e.fn.startLine,
+        bodyLineCount: e.fn.bodyLineCount,
+        qualityScore: e.fn.qualityScore ?? 0,
+        markers: uniqueMarkers,
+      }
+    })
     .sort((a, b) => {
       const impactA = a.bodyLineCount * (100 - a.qualityScore)
       const impactB = b.bodyLineCount * (100 - b.qualityScore)
@@ -140,7 +406,7 @@ export function scoreFile(
     statusBreakdown,
     pureLineCount,
     impureLineCount,
-    functions,
+    functions, // Keep all functions for drill-down (includes isInlineCallback flag)
     refactoringCandidates,
   }
 }
@@ -162,75 +428,21 @@ export function scoreDirectory(
   )
 
   if (scorableFiles.length === 0) {
+    const emptyMetrics = aggregateMetrics([])
     return {
       dirPath,
-      purity: 100,
-      impurityQuality: null,
-      health: 100,
-      pureCount: 0,
-      impureCount: 0,
+      ...emptyMetrics,
       excludedCount: fileScores.reduce((sum, f) => sum + f.excludedCount, 0),
-      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
-      pureLineCount: 0,
-      impureLineCount: 0,
       fileScores,
     }
   }
 
-  // Calculate totals
-  const totalPure = scorableFiles.reduce((sum, f) => sum + f.pureCount, 0)
-  const totalImpure = scorableFiles.reduce((sum, f) => sum + f.impureCount, 0)
-  const total = totalPure + totalImpure
-
-  // Weighted purity by function count
-  const purity = total > 0 ? (totalPure / total) * 100 : 100
-
-  // Weighted impurity quality
-  let impurityQuality: number | null = null
-  if (totalImpure > 0) {
-    const weightedQuality = scorableFiles.reduce((sum, f) => {
-      if (f.impurityQuality !== null && f.impureCount > 0) {
-        return sum + f.impurityQuality * f.impureCount
-      }
-      return sum
-    }, 0)
-    impurityQuality = weightedQuality / totalImpure
-  }
-
-  // Aggregate status breakdown
-  const statusBreakdown: StatusBreakdown = {
-    ok: scorableFiles.reduce((sum, f) => sum + f.statusBreakdown.ok, 0),
-    review: scorableFiles.reduce((sum, f) => sum + f.statusBreakdown.review, 0),
-    refactor: scorableFiles.reduce(
-      (sum, f) => sum + f.statusBreakdown.refactor,
-      0,
-    ),
-  }
-
-  // Calculate health
-  const health = total > 0 ? (statusBreakdown.ok / total) * 100 : 100
-
-  // Aggregate line counts
-  const pureLineCount = scorableFiles.reduce(
-    (sum, f) => sum + f.pureLineCount,
-    0,
-  )
-  const impureLineCount = scorableFiles.reduce(
-    (sum, f) => sum + f.impureLineCount,
-    0,
-  )
+  const aggregated = aggregateMetrics(scorableFiles)
 
   return {
     dirPath,
-    purity,
-    impurityQuality,
-    health,
-    pureCount: totalPure,
-    impureCount: totalImpure,
+    ...aggregated,
     excludedCount: fileScores.reduce((sum, f) => sum + f.excludedCount, 0),
-    statusBreakdown,
-    pureLineCount,
-    impureLineCount,
     fileScores,
   }
 }
@@ -266,19 +478,13 @@ export function scoreProject(
   )
 
   if (scorableDirs.length === 0) {
+    const emptyMetrics = aggregateMetrics([])
     return {
-      purity: 100,
-      impurityQuality: null,
-      health: 100,
-      pureCount: 0,
-      impureCount: 0,
+      ...emptyMetrics,
       excludedCount: directoryScores.reduce(
         (sum, d) => sum + d.excludedCount,
         0,
       ),
-      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
-      pureLineCount: 0,
-      impureLineCount: 0,
       directoryScores,
       timestamp,
       commitHash,
@@ -289,48 +495,7 @@ export function scoreProject(
     }
   }
 
-  // Calculate totals
-  const totalPure = scorableDirs.reduce((sum, d) => sum + d.pureCount, 0)
-  const totalImpure = scorableDirs.reduce((sum, d) => sum + d.impureCount, 0)
-  const total = totalPure + totalImpure
-
-  // Weighted purity by function count
-  const purity = total > 0 ? (totalPure / total) * 100 : 100
-
-  // Weighted impurity quality
-  let impurityQuality: number | null = null
-  if (totalImpure > 0) {
-    const weightedQuality = scorableDirs.reduce((sum, d) => {
-      if (d.impurityQuality !== null && d.impureCount > 0) {
-        return sum + d.impurityQuality * d.impureCount
-      }
-      return sum
-    }, 0)
-    impurityQuality = weightedQuality / totalImpure
-  }
-
-  // Aggregate status breakdown
-  const statusBreakdown: StatusBreakdown = {
-    ok: scorableDirs.reduce((sum, d) => sum + d.statusBreakdown.ok, 0),
-    review: scorableDirs.reduce((sum, d) => sum + d.statusBreakdown.review, 0),
-    refactor: scorableDirs.reduce(
-      (sum, d) => sum + d.statusBreakdown.refactor,
-      0,
-    ),
-  }
-
-  // Calculate health
-  const health = total > 0 ? (statusBreakdown.ok / total) * 100 : 100
-
-  // Aggregate line counts
-  const pureLineCount = scorableDirs.reduce(
-    (sum, d) => sum + d.pureLineCount,
-    0,
-  )
-  const impureLineCount = scorableDirs.reduce(
-    (sum, d) => sum + d.impureLineCount,
-    0,
-  )
+  const aggregated = aggregateMetrics(scorableDirs)
 
   // Collect all refactoring candidates across all files
   const allCandidates: RefactoringCandidate[] = []
@@ -353,15 +518,8 @@ export function scoreProject(
   })
 
   const result: ProjectScore = {
-    purity,
-    impurityQuality,
-    health,
-    pureCount: totalPure,
-    impureCount: totalImpure,
+    ...aggregated,
     excludedCount: directoryScores.reduce((sum, d) => sum + d.excludedCount, 0),
-    statusBreakdown,
-    pureLineCount,
-    impureLineCount,
     directoryScores,
     timestamp,
     commitHash,
@@ -413,6 +571,113 @@ function getDirectoryPath(filePath: string): string {
   return filePath.slice(0, lastSlash)
 }
 
+/**
+ * Truncate a relative path to a specified depth
+ *
+ * @param relativePath - A path relative to project root (e.g., "src/services/auth")
+ * @param depth - The depth to truncate to (0 = first segment, 1 = first two segments, etc.)
+ * @returns The truncated path
+ *
+ * @example
+ * getPathAtDepth('src/services/auth/utils', 1) // 'src/services'
+ * getPathAtDepth('src/services/auth/utils', 0) // 'src'
+ * getPathAtDepth('src', 5) // 'src' (depth exceeds segments)
+ */
+export function getPathAtDepth(relativePath: string, depth: number): string {
+  // Normalize path separators to forward slashes and split
+  const normalized = relativePath.replace(/\\/g, '/')
+  const segments = normalized.split('/').filter(Boolean)
+
+  if (segments.length === 0) {
+    return '.'
+  }
+
+  // depth 0 = 1 segment, depth 1 = 2 segments, etc.
+  const segmentCount = depth + 1
+
+  if (segmentCount >= segments.length) {
+    return segments.join('/')
+  }
+
+  return segments.slice(0, segmentCount).join('/')
+}
+
+/**
+ * Roll up directory scores to a specified depth
+ *
+ * Groups directories by their path truncated to the specified depth,
+ * then aggregates metrics for each group.
+ *
+ * NOTE: This is a PURE function. Directories must have relative paths
+ * (path relativization should happen in the shell layer before calling).
+ *
+ * @param directories - Array of directory scores with relative paths
+ * @param depth - The depth to roll up to (0 = top-level directories)
+ * @returns Rolled-up directory scores sorted alphabetically
+ *
+ * @example
+ * // Given directories with relative paths 'src/services/auth' and 'src/services/users'
+ * // with depth=1
+ * // Returns a single DirectoryScore for 'src/services' with aggregated metrics
+ */
+export function rollupDirectoriesByDepth(
+  directories: DirectoryScore[],
+  depth: number,
+): DirectoryScore[] {
+  if (directories.length === 0) {
+    return []
+  }
+
+  // Group directories by their truncated path
+  const groups = new Map<string, DirectoryScore[]>()
+
+  for (const dir of directories) {
+    // Truncate to specified depth (paths should already be relative)
+    const truncatedPath = getPathAtDepth(dir.dirPath, depth)
+
+    const existing = groups.get(truncatedPath)
+    if (existing) {
+      existing.push(dir)
+    } else {
+      groups.set(truncatedPath, [dir])
+    }
+  }
+
+  // Aggregate each group into a single DirectoryScore
+  const rolledUp: DirectoryScore[] = []
+
+  for (const [groupPath, groupDirs] of groups) {
+    // Filter to directories with actual functions for aggregation
+    const scorableDirs = groupDirs.filter(d => d.pureCount + d.impureCount > 0)
+
+    if (scorableDirs.length === 0) {
+      // Use aggregateMetrics for empty case to ensure consistency
+      const emptyMetrics = aggregateMetrics([])
+      rolledUp.push({
+        dirPath: groupPath,
+        ...emptyMetrics,
+        excludedCount: groupDirs.reduce((sum, d) => sum + d.excludedCount, 0),
+        fileScores: [],
+      })
+      continue
+    }
+
+    const aggregated = aggregateMetrics(scorableDirs)
+
+    rolledUp.push({
+      dirPath: groupPath,
+      ...aggregated,
+      excludedCount: groupDirs.reduce((sum, d) => sum + d.excludedCount, 0),
+      fileScores: [],
+    })
+  }
+
+  // Sort alphabetically by path
+  rolledUp.sort((a, b) => a.dirPath.localeCompare(b.dirPath))
+
+  return rolledUp
+}
+
 /**
  * Calculate delta between two project scores
  *