fcis 0.1.0

package/src/scoring/scorer.ts

@@ -0,0 +1,504 @@
+/**
+ * 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'
+ */
+
+import type {
+  ClassifiedFunction,
+  DirectoryScore,
+  FileScore,
+  ProjectScore,
+  RefactoringCandidate,
+  StatusBreakdown,
+} from '../types.js'
+
+/**
+ * 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
+ */
+export function scoreFile(
+  filePath: string,
+  functions: ClassifiedFunction[],
+  isTypeOnly: boolean = false,
+): FileScore {
+  // Handle type-only files
+  if (isTypeOnly) {
+    return {
+      filePath,
+      purity: 100,
+      impurityQuality: null,
+      health: 100,
+      pureCount: 0,
+      impureCount: 0,
+      excludedCount: 0,
+      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
+      pureLineCount: 0,
+      impureLineCount: 0,
+      functions: [],
+      refactoringCandidates: [],
+      typeOnly: true,
+    }
+  }
+
+  // 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
+
+  // Handle empty files
+  if (total === 0) {
+    return {
+      filePath,
+      purity: 100,
+      impurityQuality: null,
+      health: 100,
+      pureCount: 0,
+      impureCount: 0,
+      excludedCount: 0,
+      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
+      pureLineCount: 0,
+      impureLineCount: 0,
+      functions: [],
+      refactoringCandidates: [],
+      allExcluded: true,
+    }
+  }
+
+  // Calculate purity (percentage of pure functions)
+  const purity = (pureCount / total) * 100
+
+  // Calculate impurity quality (average quality of impure functions)
+  let impurityQuality: number | null = null
+  if (impureCount > 0) {
+    const totalQuality = impureFunctions.reduce(
+      (sum, f) => sum + (f.qualityScore ?? 0),
+      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,
+  )
+
+  // Get refactoring candidates (functions with status 'refactor')
+  // 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),
+    }))
+    .sort((a, b) => {
+      const impactA = a.bodyLineCount * (100 - a.qualityScore)
+      const impactB = b.bodyLineCount * (100 - b.qualityScore)
+      return impactB - impactA
+    })
+
+  return {
+    filePath,
+    purity,
+    impurityQuality,
+    health,
+    pureCount,
+    impureCount,
+    excludedCount: 0,
+    statusBreakdown,
+    pureLineCount,
+    impureLineCount,
+    functions,
+    refactoringCandidates,
+  }
+}
+
+/**
+ * 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
+ */
+export function scoreDirectory(
+  dirPath: string,
+  fileScores: FileScore[],
+): DirectoryScore {
+  // Filter out type-only and empty files for aggregation
+  const scorableFiles = fileScores.filter(
+    f => !f.typeOnly && !f.allExcluded && f.pureCount + f.impureCount > 0,
+  )
+
+  if (scorableFiles.length === 0) {
+    return {
+      dirPath,
+      purity: 100,
+      impurityQuality: null,
+      health: 100,
+      pureCount: 0,
+      impureCount: 0,
+      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,
+  )
+
+  return {
+    dirPath,
+    purity,
+    impurityQuality,
+    health,
+    pureCount: totalPure,
+    impureCount: totalImpure,
+    excludedCount: fileScores.reduce((sum, f) => sum + f.excludedCount, 0),
+    statusBreakdown,
+    pureLineCount,
+    impureLineCount,
+    fileScores,
+  }
+}
+
+/**
+ * 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
+ */
+export function scoreProject(
+  directoryScores: DirectoryScore[],
+  options: {
+    timestamp?: string
+    commitHash?: string | null
+    subset?: boolean
+    filesGlob?: string
+    errors?: { filePath: string; error: string }[]
+  } = {},
+): ProjectScore {
+  const {
+    timestamp = new Date().toISOString(),
+    commitHash = null,
+    subset = false,
+    filesGlob,
+    errors = [],
+  } = options
+
+  // Filter directories with actual functions
+  const scorableDirs = directoryScores.filter(
+    d => d.pureCount + d.impureCount > 0,
+  )
+
+  if (scorableDirs.length === 0) {
+    return {
+      purity: 100,
+      impurityQuality: null,
+      health: 100,
+      pureCount: 0,
+      impureCount: 0,
+      excludedCount: directoryScores.reduce(
+        (sum, d) => sum + d.excludedCount,
+        0,
+      ),
+      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
+      pureLineCount: 0,
+      impureLineCount: 0,
+      directoryScores,
+      timestamp,
+      commitHash,
+      refactoringCandidates: [],
+      allExcluded: true,
+      ...(subset && { subset: true, filesGlob }),
+      ...(errors.length > 0 && { errors }),
+    }
+  }
+
+  // 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,
+  )
+
+  // Collect all refactoring candidates across all files
+  const allCandidates: RefactoringCandidate[] = []
+  for (const dir of directoryScores) {
+    for (const file of dir.fileScores) {
+      for (const candidate of file.refactoringCandidates) {
+        allCandidates.push({
+          ...candidate,
+          filePath: file.filePath,
+        })
+      }
+    }
+  }
+
+  // Sort by impact: bodyLineCount × (100 - qualityScore) descending
+  const refactoringCandidates = allCandidates.sort((a, b) => {
+    const impactA = a.bodyLineCount * (100 - a.qualityScore)
+    const impactB = b.bodyLineCount * (100 - b.qualityScore)
+    return impactB - impactA
+  })
+
+  const result: ProjectScore = {
+    purity,
+    impurityQuality,
+    health,
+    pureCount: totalPure,
+    impureCount: totalImpure,
+    excludedCount: directoryScores.reduce((sum, d) => sum + d.excludedCount, 0),
+    statusBreakdown,
+    pureLineCount,
+    impureLineCount,
+    directoryScores,
+    timestamp,
+    commitHash,
+    refactoringCandidates,
+  }
+
+  if (subset && filesGlob !== undefined) {
+    result.subset = true
+    result.filesGlob = filesGlob
+  }
+
+  if (errors.length > 0) {
+    result.errors = errors
+  }
+
+  return result
+}
+
+/**
+ * Group file scores by directory
+ *
+ * @param fileScores - Array of file scores
+ * @returns Map of directory path to file scores
+ */
+export function groupFilesByDirectory(
+  fileScores: FileScore[],
+): Map<string, FileScore[]> {
+  const groups = new Map<string, FileScore[]>()
+
+  for (const fileScore of fileScores) {
+    const dirPath = getDirectoryPath(fileScore.filePath)
+    const existing = groups.get(dirPath)
+    if (existing) {
+      existing.push(fileScore)
+    } else {
+      groups.set(dirPath, [fileScore])
+    }
+  }
+
+  return groups
+}
+
+/**
+ * Get directory path from file path
+ */
+function getDirectoryPath(filePath: string): string {
+  const lastSlash = filePath.lastIndexOf('/')
+  if (lastSlash === -1) return '.'
+  return filePath.slice(0, lastSlash)
+}
+
+/**
+ * Calculate delta between two project scores
+ *
+ * @param current - Current project score
+ * @param previous - Previous project score
+ * @returns Delta metrics
+ */
+export function calculateDelta(
+  current: ProjectScore,
+  previous: ProjectScore,
+): {
+  purityDelta: number
+  impurityQualityDelta: number | null
+  healthDelta: number
+  pureCountDelta: number
+  impureCountDelta: number
+} {
+  return {
+    purityDelta: current.purity - previous.purity,
+    impurityQualityDelta:
+      current.impurityQuality !== null && previous.impurityQuality !== null
+        ? current.impurityQuality - previous.impurityQuality
+        : null,
+    healthDelta: current.health - previous.health,
+    pureCountDelta: current.pureCount - previous.pureCount,
+    impureCountDelta: current.impureCount - previous.impureCount,
+  }
+}
+
+/**
+ * Get diagnostic insights based on metrics
+ *
+ * @param score - Project or file score
+ * @returns Array of insight messages
+ */
+export function getDiagnosticInsights(
+  score: Pick<ProjectScore, 'purity' | 'impurityQuality' | 'health'>,
+): string[] {
+  const insights: string[] = []
+
+  // High purity + low impurity quality
+  if (
+    score.purity >= 60 &&
+    score.impurityQuality !== null &&
+    score.impurityQuality < 50
+  ) {
+    insights.push(
+      'Most code is pure, but the impure code is tangled. Focus on improving the structure of impure functions.',
+    )
+  }
+
+  // Low purity + high impurity quality
+  if (
+    score.purity < 40 &&
+    score.impurityQuality !== null &&
+    score.impurityQuality >= 70
+  ) {
+    insights.push(
+      "Lots of I/O code, but it's well-structured. Consider extracting more pure business logic.",
+    )
+  }
+
+  // Low purity + low impurity quality
+  if (
+    score.purity < 40 &&
+    score.impurityQuality !== null &&
+    score.impurityQuality < 50
+  ) {
+    insights.push(
+      'Significant technical debt in I/O code. Both purity and structure need improvement.',
+    )
+  }
+
+  // High health with low purity
+  if (score.health >= 80 && score.purity < 50) {
+    insights.push(
+      'Despite low purity, impure functions are well-structured. Good FCIS patterns in shell code.',
+    )
+  }
+
+  // Low health
+  if (score.health < 50) {
+    insights.push(
+      'More than half of functions need attention. Prioritize refactoring candidates.',
+    )
+  }
+
+  return insights
+}