fcis 0.1.0

package/src/extraction/extractor.ts

@@ -0,0 +1,188 @@
+/**
+ * Extractor - Shell layer for loading TypeScript projects via ts-morph
+ *
+ * This module handles the I/O of loading a TypeScript project from disk.
+ * It's a thin shell that delegates to ts-morph for actual parsing.
+ */
+
+import { Project, SourceFile } from 'ts-morph'
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+
+/**
+ * Strips JSON comments (both line // and block /* comments)
+ * This allows parsing tsconfig.json files that contain comments
+ */
+export function stripJsonComments(jsonString: string): string {
+  let result = ''
+  let inString = false
+  let inLineComment = false
+  let inBlockComment = false
+  let i = 0
+
+  while (i < jsonString.length) {
+    const char = jsonString[i]
+    const nextChar = jsonString[i + 1]
+
+    // Handle string state (don't strip comments inside strings)
+    if (!inLineComment && !inBlockComment && char === '"') {
+      // Check if this quote is escaped
+      let backslashCount = 0
+      let j = i - 1
+      while (j >= 0 && jsonString[j] === '\\') {
+        backslashCount++
+        j--
+      }
+      if (backslashCount % 2 === 0) {
+        inString = !inString
+      }
+    }
+
+    if (inString) {
+      result += char
+      i++
+      continue
+    }
+
+    // Handle line comment start
+    if (!inBlockComment && char === '/' && nextChar === '/') {
+      inLineComment = true
+      i += 2
+      continue
+    }
+
+    // Handle line comment end
+    if (inLineComment && (char === '\n' || char === '\r')) {
+      inLineComment = false
+      result += char
+      i++
+      continue
+    }
+
+    // Handle block comment start
+    if (!inLineComment && char === '/' && nextChar === '*') {
+      inBlockComment = true
+      i += 2
+      continue
+    }
+
+    // Handle block comment end
+    if (inBlockComment && char === '*' && nextChar === '/') {
+      inBlockComment = false
+      i += 2
+      continue
+    }
+
+    // Add character if not in a comment
+    if (!inLineComment && !inBlockComment) {
+      result += char
+    }
+
+    i++
+  }
+
+  return result
+}
+
+export type ExtractorOptions = {
+  tsconfigPath: string
+  filesGlob?: string
+}
+
+export type ExtractorResult = {
+  project: Project
+  sourceFiles: SourceFile[]
+  errors: { filePath: string; error: string }[]
+}
+
+/**
+ * Loads a TypeScript project from a tsconfig.json path
+ *
+ * @param options - Configuration options for the extractor
+ * @returns The loaded project and source files
+ * @throws Error if tsconfig.json doesn't exist or is invalid
+ */
+export function loadProject(options: ExtractorOptions): ExtractorResult {
+  const { tsconfigPath, filesGlob } = options
+  const errors: { filePath: string; error: string }[] = []
+
+  // Validate tsconfig exists
+  const absoluteTsconfigPath = path.resolve(tsconfigPath)
+  if (!fs.existsSync(absoluteTsconfigPath)) {
+    throw new Error(`tsconfig.json not found at: ${absoluteTsconfigPath}`)
+  }
+
+  // Validate tsconfig is valid JSON (strip comments first since TypeScript allows them)
+  try {
+    const content = fs.readFileSync(absoluteTsconfigPath, 'utf-8')
+    const strippedContent = stripJsonComments(content)
+    JSON.parse(strippedContent)
+  } catch (e) {
+    throw new Error(
+      `Invalid tsconfig.json at ${absoluteTsconfigPath}: ${e instanceof Error ? e.message : String(e)}`,
+    )
+  }
+
+  // Create the ts-morph project
+  const project = new Project({
+    tsConfigFilePath: absoluteTsconfigPath,
+    skipAddingFilesFromTsConfig: false,
+  })
+
+  // Get source files, filtering to .ts only (excluding .tsx for v1)
+  let sourceFiles = project.getSourceFiles().filter(sf => {
+    const filePath = sf.getFilePath()
+    // Include only .ts files, exclude .tsx, .d.ts, test files, and generated files
+    return (
+      filePath.endsWith('.ts') &&
+      !filePath.endsWith('.d.ts') &&
+      !filePath.endsWith('.test.ts') &&
+      !filePath.endsWith('.spec.ts') &&
+      !filePath.includes('/node_modules/') &&
+      !filePath.includes('/generated/')
+    )
+  })
+
+  // Apply files glob filter if provided
+  if (filesGlob) {
+    const globPattern = createGlobMatcher(filesGlob)
+    sourceFiles = sourceFiles.filter(sf => globPattern(sf.getFilePath()))
+  }
+
+  return {
+    project,
+    sourceFiles,
+    errors,
+  }
+}
+
+/**
+ * Creates a simple glob matcher function
+ * Supports basic glob patterns: *, **, ?
+ */
+function createGlobMatcher(glob: string): (filePath: string) => boolean {
+  // Convert glob to regex
+  const regexStr = glob
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape special regex chars except * and ?
+    .replace(/\*\*/g, '{{DOUBLE_STAR}}') // Placeholder for **
+    .replace(/\*/g, '[^/]*') // * matches anything except /
+    .replace(/\?/g, '.') // ? matches single char
+    .replace(/\{\{DOUBLE_STAR\}\}/g, '.*') // ** matches anything including /
+
+  const regex = new RegExp(regexStr)
+
+  return (filePath: string) => regex.test(filePath)
+}
+
+/**
+ * Gets the commit hash from git if available
+ */
+export function getCommitHash(): string | null {
+  try {
+    const { execSync } = require('node:child_process')
+    const hash = execSync('git rev-parse HEAD', { encoding: 'utf-8' }).trim()
+    return hash
+  } catch {
+    return null
+  }
+}

package/src/index.ts

@@ -0,0 +1,111 @@
+/**
+ * FCIS Analyzer - Public API
+ *
+ * Functional Core, Imperative Shell analyzer for TypeScript codebases.
+ *
+ * @module @schoolai/fcis
+ */
+
+// Main analyzer function
+export {
+  analyze,
+  analyzeFile,
+  analyzeFilePath,
+  checkThresholds,
+} from './analyzer.js'
+
+// Types
+export type {
+  // Core types
+  CallSite,
+  ExtractedFunction,
+  FileImports,
+  MarkerType,
+  ImpurityMarker,
+  FunctionClassification,
+  Status,
+  ClassifiedFunction,
+  // Score types
+  StatusBreakdown,
+  RefactoringCandidate,
+  FileScore,
+  DirectoryScore,
+  ProjectScore,
+  // Config types
+  AnalyzerConfig,
+  QualityThresholds,
+  AnalysisError,
+  ExtractionResult,
+  DetectionContext,
+} from './types.js'
+
+export { DEFAULT_QUALITY_THRESHOLDS } from './types.js'
+
+// Detection
+export {
+  detectMarkers,
+  createDetectionContext,
+  getPureImportedFunctions,
+} from './detection/detect-markers.js'
+export {
+  MARKER_CATALOG,
+  getMarkerDefinition,
+  getAllMarkerTypes,
+} from './detection/markers.js'
+export type { MarkerDefinition } from './detection/markers.js'
+
+// Classification
+export {
+  classifyFunction,
+  shouldExcludeFunction,
+  createClassifiedFunction,
+} from './classification/classifier.js'
+export {
+  computeQualityScore,
+  analyzeFunction as analyzeFunctionQuality,
+  QUALITY_WEIGHTS,
+} from './classification/quality-scorer.js'
+export type { FunctionAnalysis } from './classification/quality-scorer.js'
+export {
+  deriveStatus,
+  getStatusDescription,
+  getStatusEmoji,
+  getStatusColor,
+} from './classification/derive-status.js'
+
+// Scoring
+export {
+  scoreFile,
+  scoreDirectory,
+  scoreProject,
+  groupFilesByDirectory,
+  calculateDelta,
+  getDiagnosticInsights,
+} from './scoring/scorer.js'
+
+// Reporting
+export {
+  generateJsonReport,
+  writeJsonReport,
+  readJsonReport,
+  createSummaryJson,
+  generateComparisonReport,
+} from './reporting/report-json.js'
+export type { JsonReportOptions } from './reporting/report-json.js'
+export {
+  printConsoleReport,
+  generateSummaryLine,
+  printFileReport,
+} from './reporting/report-console.js'
+
+// Extraction (for advanced use cases)
+export { loadProject, getCommitHash } from './extraction/extractor.js'
+export type {
+  ExtractorOptions,
+  ExtractorResult,
+} from './extraction/extractor.js'
+export {
+  extractFunctions,
+  extractImports,
+  isTypeOnlyFile,
+} from './extraction/extract-functions.js'

package/src/reporting/report-console.ts

@@ -0,0 +1,416 @@
+/**
+ * Console Report Generator - Shell Layer
+ *
+ * Produces human-readable console output with colors, visual bars,
+ * and formatted tables. This is part of the SHELL layer as it
+ * performs I/O (writing to console).
+ */
+
+import chalk from 'chalk'
+import * as path from 'node:path'
+
+import type {
+  DirectoryScore,
+  FileScore,
+  ProjectScore,
+  RefactoringCandidate,
+  StatusBreakdown,
+} from '../types.js'
+import { getDiagnosticInsights } from '../scoring/scorer.js'
+import {
+  getStatusColor,
+  getStatusEmoji,
+} from '../classification/derive-status.js'
+
+/**
+ * Generate and print the full console report
+ */
+export function printConsoleReport(
+  score: ProjectScore,
+  options: { verbose?: boolean } = {},
+): void {
+  const { verbose = false } = options
+
+  printHeader()
+  printProjectSummary(score)
+  printStatusBreakdown(
+    score.statusBreakdown,
+    score.pureCount + score.impureCount,
+  )
+  printInsights(score)
+
+  if (verbose) {
+    printDirectoryBreakdown(score.directoryScores)
+  } else {
+    printWorstDirectories(score.directoryScores)
+  }
+
+  printRefactoringCandidates(score.refactoringCandidates.slice(0, 10))
+
+  if (score.errors && score.errors.length > 0) {
+    printErrors(score.errors)
+  }
+
+  printFooter(score)
+}
+
+/**
+ * Print the report header
+ */
+function printHeader(): void {
+  console.log()
+  console.log(chalk.bold('FCIS Analysis'))
+  console.log(
+    chalk.gray('═══════════════════════════════════════════════════════════'),
+  )
+  console.log()
+}
+
+/**
+ * Print the project summary with visual bars
+ */
+function printProjectSummary(score: ProjectScore): void {
+  const healthBar = createProgressBar(score.health, 25)
+
+  const healthColor =
+    score.health >= 70
+      ? chalk.green
+      : score.health >= 50
+        ? chalk.yellow
+        : chalk.red
+  const purityColor =
+    score.purity >= 70
+      ? chalk.green
+      : score.purity >= 50
+        ? chalk.yellow
+        : chalk.red
+
+  console.log(
+    `Project Health: ${healthColor(score.health.toFixed(0) + '%')} ${healthBar}`,
+  )
+  console.log(
+    `  Purity:           ${purityColor(score.purity.toFixed(0) + '%')} (${score.pureCount} pure / ${score.pureCount + score.impureCount} total)`,
+  )
+
+  if (score.impurityQuality !== null) {
+    const qualityColor =
+      score.impurityQuality >= 70
+        ? chalk.green
+        : score.impurityQuality >= 50
+          ? chalk.yellow
+          : chalk.red
+    console.log(
+      `  Impurity Quality: ${qualityColor(score.impurityQuality.toFixed(0) + '%')} average`,
+    )
+  }
+
+  console.log()
+}
+
+/**
+ * Print status breakdown
+ */
+function printStatusBreakdown(breakdown: StatusBreakdown, total: number): void {
+  console.log('Status Breakdown:')
+
+  const okPercent = total > 0 ? ((breakdown.ok / total) * 100).toFixed(0) : '0'
+  const reviewPercent =
+    total > 0 ? ((breakdown.review / total) * 100).toFixed(0) : '0'
+  const refactorPercent =
+    total > 0 ? ((breakdown.refactor / total) * 100).toFixed(0) : '0'
+
+  console.log(
+    `  ${chalk.green('✓ OK:')}       ${String(breakdown.ok).padStart(4)} functions (${okPercent}%)  — no action needed`,
+  )
+  console.log(
+    `  ${chalk.yellow('◐ Review:')}   ${String(breakdown.review).padStart(4)} functions (${reviewPercent}%)  — could be improved`,
+  )
+  console.log(
+    `  ${chalk.red('✗ Refactor:')} ${String(breakdown.refactor).padStart(4)} functions (${refactorPercent}%)  — tangled, needs work`,
+  )
+
+  console.log()
+}
+
+/**
+ * Print diagnostic insights
+ */
+function printInsights(score: ProjectScore): void {
+  const insights = getDiagnosticInsights(score)
+
+  if (insights.length > 0) {
+    console.log(chalk.bold('Insights:'))
+    for (const insight of insights) {
+      console.log(`  ${chalk.cyan('→')} ${insight}`)
+    }
+    console.log()
+  }
+}
+
+/**
+ * Print directory breakdown (verbose mode)
+ */
+function printDirectoryBreakdown(directories: DirectoryScore[]): void {
+  // Sort by health ascending (worst first)
+  const sorted = [...directories]
+    .filter(d => d.pureCount + d.impureCount > 0)
+    .sort((a, b) => a.health - b.health)
+
+  if (sorted.length === 0) return
+
+  console.log(chalk.bold('Directory Breakdown:'))
+  console.log(chalk.gray('─'.repeat(80)))
+  console.log(
+    chalk.gray(
+      padEnd('Directory', 45) +
+        padEnd('Health', 10) +
+        padEnd('Purity', 10) +
+        padEnd('Functions', 15),
+    ),
+  )
+  console.log(chalk.gray('─'.repeat(80)))
+
+  for (const dir of sorted) {
+    const healthColor =
+      dir.health >= 70
+        ? chalk.green
+        : dir.health >= 50
+          ? chalk.yellow
+          : chalk.red
+    const purityColor =
+      dir.purity >= 70
+        ? chalk.green
+        : dir.purity >= 50
+          ? chalk.yellow
+          : chalk.red
+
+    const relativePath = toRelativePath(dir.dirPath)
+    const total = dir.pureCount + dir.impureCount
+
+    console.log(
+      padEnd(relativePath, 45) +
+        healthColor(padEnd(dir.health.toFixed(0) + '%', 10)) +
+        purityColor(padEnd(dir.purity.toFixed(0) + '%', 10)) +
+        padEnd(`${dir.pureCount}/${total}`, 15),
+    )
+  }
+
+  console.log()
+}
+
+/**
+ * Print worst directories (non-verbose mode)
+ */
+function printWorstDirectories(directories: DirectoryScore[]): void {
+  const sorted = [...directories]
+    .filter(d => d.pureCount + d.impureCount > 0 && d.health < 70)
+    .sort((a, b) => a.health - b.health)
+    .slice(0, 5)
+
+  if (sorted.length === 0) return
+
+  console.log(chalk.bold('Directories Needing Attention:'))
+
+  for (const dir of sorted) {
+    const healthColor = dir.health >= 50 ? chalk.yellow : chalk.red
+    const total = dir.pureCount + dir.impureCount
+    const relativePath = toRelativePath(dir.dirPath)
+
+    console.log(
+      `  ${healthColor(dir.health.toFixed(0).padStart(3) + '%')} ` +
+        chalk.gray(`(${dir.pureCount}/${total} pure)`) +
+        ` ${relativePath}`,
+    )
+  }
+
+  console.log()
+}
+
+/**
+ * Print refactoring candidates
+ */
+function printRefactoringCandidates(candidates: RefactoringCandidate[]): void {
+  if (candidates.length === 0) {
+    console.log(chalk.green('No refactoring candidates found. Great job!'))
+    console.log()
+    return
+  }
+
+  console.log(chalk.bold('Top Refactoring Candidates:'))
+  console.log(chalk.gray('(Sorted by impact: size × complexity)'))
+  console.log()
+
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i]
+    if (!candidate) continue
+
+    const qualityColor = candidate.qualityScore >= 40 ? chalk.yellow : chalk.red
+    const relativePath = toRelativePath(candidate.filePath)
+
+    console.log(
+      chalk.gray(`${(i + 1).toString().padStart(2)}.`) +
+        ` ${qualityColor(candidate.qualityScore.toFixed(0).padStart(3))}` +
+        chalk.gray('/100') +
+        ` ${chalk.cyan(candidate.name ?? '<anonymous>')}` +
+        chalk.gray(` (${candidate.bodyLineCount} lines)`),
+    )
+    console.log(chalk.gray(`      ${relativePath}:${candidate.startLine}`))
+
+    if (candidate.markers.length > 0) {
+      const markerStr = candidate.markers.slice(0, 3).join(', ')
+      const more =
+        candidate.markers.length > 3
+          ? ` +${candidate.markers.length - 3} more`
+          : ''
+      console.log(chalk.gray(`      Markers: ${markerStr}${more}`))
+    }
+
+    console.log()
+  }
+}
+
+/**
+ * Print errors encountered during analysis
+ */
+function printErrors(errors: { filePath: string; error: string }[]): void {
+  console.log(chalk.yellow.bold(`Errors (${errors.length} files skipped):`))
+
+  for (const err of errors.slice(0, 5)) {
+    console.log(`  ${chalk.yellow('!')} ${err.filePath}`)
+    console.log(chalk.gray(`      ${err.error}`))
+  }
+
+  if (errors.length > 5) {
+    console.log(chalk.gray(`  ... and ${errors.length - 5} more`))
+  }
+
+  console.log()
+}
+
+/**
+ * Print the report footer
+ */
+function printFooter(score: ProjectScore): void {
+  console.log(
+    chalk.gray('═══════════════════════════════════════════════════════════'),
+  )
+
+  const timestamp = new Date(score.timestamp).toLocaleString()
+  console.log(chalk.gray(`Generated: ${timestamp}`))
+
+  if (score.commitHash) {
+    console.log(chalk.gray(`Commit: ${score.commitHash.slice(0, 8)}`))
+  }
+
+  if (score.subset) {
+    console.log(chalk.yellow(`Subset analysis: ${score.filesGlob}`))
+  }
+
+  console.log()
+}
+
+/**
+ * Create a visual progress bar
+ */
+function createProgressBar(percent: number, width: number): string {
+  const filled = Math.round((percent / 100) * width)
+  const empty = width - filled
+
+  const filledChar = '█'
+  const emptyChar = '░'
+
+  const bar = filledChar.repeat(filled) + emptyChar.repeat(empty)
+
+  if (percent >= 70) {
+    return chalk.green(bar)
+  } else if (percent >= 50) {
+    return chalk.yellow(bar)
+  } else {
+    return chalk.red(bar)
+  }
+}
+
+/**
+ * Generate a single-line summary suitable for CI output
+ */
+export function generateSummaryLine(score: ProjectScore): string {
+  const parts = [
+    `FCIS Health: ${score.health.toFixed(0)}%`,
+    `Purity: ${score.purity.toFixed(0)}%`,
+  ]
+
+  if (score.impurityQuality !== null) {
+    parts.push(`Impurity Quality: ${score.impurityQuality.toFixed(0)}%`)
+  }
+
+  return parts.join(' | ')
+}
+
+/**
+ * Convert an absolute path to a path relative to the current working directory
+ */
+function toRelativePath(absolutePath: string): string {
+  const cwd = process.cwd()
+  if (absolutePath.startsWith(cwd)) {
+    const relative = path.relative(cwd, absolutePath)
+    return relative || '.'
+  }
+  return absolutePath
+}
+
+/**
+ * Pad end of string to a fixed length
+ */
+function padEnd(str: string, length: number): string {
+  if (str.length >= length) return str.slice(0, length)
+  return str + ' '.repeat(length - str.length)
+}
+
+/**
+ * Print a file-level report (for verbose output)
+ */
+export function printFileReport(fileScore: FileScore): void {
+  const healthColor =
+    fileScore.health >= 70
+      ? chalk.green
+      : fileScore.health >= 50
+        ? chalk.yellow
+        : chalk.red
+  const total = fileScore.pureCount + fileScore.impureCount
+  const relativePath = toRelativePath(fileScore.filePath)
+
+  console.log()
+  console.log(chalk.bold(relativePath))
+  console.log(
+    `  Health: ${healthColor(fileScore.health.toFixed(0) + '%')} | ` +
+      `Purity: ${fileScore.purity.toFixed(0)}% | ` +
+      `Functions: ${fileScore.pureCount}/${total} pure`,
+  )
+
+  if (fileScore.functions.length > 0 && fileScore.impureCount > 0) {
+    console.log()
+    console.log('  Functions:')
+
+    for (const fn of fileScore.functions) {
+      const statusEmoji = getStatusEmoji(fn.status)
+      const statusColor = getStatusColor(fn.status)
+      const colorFn =
+        statusColor === 'green'
+          ? chalk.green
+          : statusColor === 'yellow'
+            ? chalk.yellow
+            : chalk.red
+
+      const name = fn.name ?? '<anonymous>'
+      const classification =
+        fn.classification === 'pure'
+          ? chalk.green('pure')
+          : chalk.yellow('impure')
+      const quality = fn.qualityScore !== null ? ` (${fn.qualityScore})` : ''
+
+      console.log(
+        `    ${colorFn(statusEmoji)} ${name} — ${classification}${quality}`,
+      )
+    }
+  }
+}