fcis 0.1.0

package/src/reporting/report-json.ts

@@ -0,0 +1,232 @@
+/**
+ * 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
+ */
+
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+
+import type { ProjectScore } from '../types.js'
+
+/**
+ * JSON report options
+ */
+export type JsonReportOptions = {
+  pretty?: boolean // Pretty print with indentation (default: true)
+  includeFunction?: boolean // Include function details (default: false for smaller output)
+}
+
+/**
+ * Generate JSON report string from project score
+ *
+ * @param score - The project score to serialize
+ * @param options - Report options
+ * @returns JSON string representation
+ */
+export function generateJsonReport(
+  score: ProjectScore,
+  options: JsonReportOptions = {},
+): string {
+  const { pretty = true, includeFunction = false } = options
+
+  // Create a copy to potentially filter out function details
+  const reportData = prepareReportData(score, includeFunction)
+
+  if (pretty) {
+    return JSON.stringify(reportData, null, 2)
+  }
+
+  return JSON.stringify(reportData)
+}
+
+/**
+ * Prepare report data, optionally excluding function details for smaller output
+ */
+function prepareReportData(
+  score: ProjectScore,
+  includeFunctions: boolean,
+): ProjectScore {
+  if (includeFunctions) {
+    return score
+  }
+
+  // Create a shallow copy with stripped function details
+  return {
+    ...score,
+    directoryScores: score.directoryScores.map(dir => ({
+      ...dir,
+      fileScores: dir.fileScores.map(file => ({
+        ...file,
+        functions: [], // Strip function details to reduce size
+      })),
+    })),
+  }
+}
+
+/**
+ * Write JSON report to file
+ *
+ * @param score - The project score to write
+ * @param outputPath - Path to write the JSON file
+ * @param options - Report options
+ */
+export function writeJsonReport(
+  score: ProjectScore,
+  outputPath: string,
+  options: JsonReportOptions = {},
+): void {
+  const json = generateJsonReport(score, options)
+
+  // Ensure directory exists
+  const dir = path.dirname(outputPath)
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+
+  fs.writeFileSync(outputPath, json, 'utf-8')
+}
+
+/**
+ * Read a previous JSON report from file
+ *
+ * @param inputPath - Path to the JSON file
+ * @returns Parsed ProjectScore or null if file doesn't exist
+ */
+export function readJsonReport(inputPath: string): ProjectScore | null {
+  if (!fs.existsSync(inputPath)) {
+    return null
+  }
+
+  const content = fs.readFileSync(inputPath, 'utf-8')
+  return JSON.parse(content) as ProjectScore
+}
+
+/**
+ * Create a summary JSON suitable for PR comments or CI output
+ *
+ * @param score - The project score
+ * @returns Minimal JSON object with key metrics
+ */
+export 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
+  }>
+} {
+  return {
+    health: Math.round(score.health * 10) / 10,
+    purity: Math.round(score.purity * 10) / 10,
+    impurityQuality:
+      score.impurityQuality !== null
+        ? Math.round(score.impurityQuality * 10) / 10
+        : null,
+    pureCount: score.pureCount,
+    impureCount: score.impureCount,
+    statusBreakdown: score.statusBreakdown,
+    timestamp: score.timestamp,
+    commitHash: score.commitHash,
+    topRefactoringCandidates: score.refactoringCandidates
+      .slice(0, 5)
+      .map(c => ({
+        name: c.name,
+        filePath: c.filePath,
+        qualityScore: c.qualityScore,
+      })),
+  }
+}
+
+/**
+ * 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
+ */
+export 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
+  }>
+} {
+  const currentSummary = createSummaryJson(current)
+  const previousSummary = createSummaryJson(previous)
+
+  // Calculate deltas
+  const delta = {
+    health: Math.round((current.health - previous.health) * 10) / 10,
+    purity: Math.round((current.purity - previous.purity) * 10) / 10,
+    impurityQuality:
+      current.impurityQuality !== null && previous.impurityQuality !== null
+        ? Math.round(
+            (current.impurityQuality - previous.impurityQuality) * 10,
+          ) / 10
+        : null,
+    pureCount: current.pureCount - previous.pureCount,
+    impureCount: current.impureCount - previous.impureCount,
+  }
+
+  // Find new and resolved refactoring candidates
+  const currentCandidateKeys = new Set(
+    current.refactoringCandidates.map(c => `${c.filePath}:${c.name}`),
+  )
+  const previousCandidateKeys = new Set(
+    previous.refactoringCandidates.map(c => `${c.filePath}:${c.name}`),
+  )
+
+  const newRefactoringCandidates = current.refactoringCandidates
+    .filter(c => !previousCandidateKeys.has(`${c.filePath}:${c.name}`))
+    .map(c => ({ name: c.name, filePath: c.filePath }))
+
+  const resolvedRefactoringCandidates = previous.refactoringCandidates
+    .filter(c => !currentCandidateKeys.has(`${c.filePath}:${c.name}`))
+    .map(c => ({ name: c.name, filePath: c.filePath }))
+
+  // Overall improvement check (health went up or stayed same with other improvements)
+  const improved =
+    delta.health > 0 ||
+    (delta.health >= 0 && delta.purity > 0) ||
+    (delta.health >= 0 &&
+      delta.impurityQuality !== null &&
+      delta.impurityQuality > 0)
+
+  return {
+    current: currentSummary,
+    previous: previousSummary,
+    delta,
+    improved,
+    newRefactoringCandidates,
+    resolvedRefactoringCandidates,
+  }
+}