fcis 0.1.0

package/src/types.ts

@@ -0,0 +1,248 @@
+/**
+ * Core type definitions for the FCIS Analyzer
+ *
+ * These types form the contract between the analyzer's layers:
+ * - Extraction layer produces ExtractedFunction and FileImports
+ * - Detection layer produces ImpurityMarker[]
+ * - Classification layer produces ClassifiedFunction
+ * - Scoring layer produces FileScore, DirectoryScore, ProjectScore
+ */
+
+/**
+ * CallSite captures position and context for each call expression,
+ * enabling sequence analysis (GATHER→DECIDE→EXECUTE detection)
+ */
+export type CallSite = {
+  expression: string // e.g. "db.user.findFirst", "planAcceptInvite"
+  line: number // position within the function (relative to function start)
+  isAwaited: boolean // was this call preceded by `await`?
+}
+
+/**
+ * Represents a function extracted from source code
+ */
+export type ExtractedFunction = {
+  name: string | null
+  filePath: string
+  startLine: number
+  endLine: number
+  isAsync: boolean
+  isExported: boolean
+  bodyLineCount: number
+  statementCount: number
+  hasConditionals: boolean
+  parentContext: string | null // e.g. class name, variable name
+  callSites: CallSite[] // enriched call expressions with position and await context
+  hasAwait: boolean // convenience flag: true if any callSite.isAwaited
+  propertyAccessChains: string[] // e.g. ["process.env.NODE_ENV", "db.user"]
+  kind:
+    | 'function'
+    | 'method'
+    | 'arrow'
+    | 'function-expression'
+    | 'getter'
+    | 'setter'
+}
+
+/**
+ * Represents imports in a file
+ */
+export type FileImports = {
+  filePath: string
+  imports: {
+    moduleSpecifier: string // e.g. "@sai/database", "./organizations.pure"
+    namedImports: string[] // e.g. ["planAcceptInvite", "AcceptInviteDecision"]
+  }[]
+}
+
+/**
+ * Strict marker type union — prevents typos, enables exhaustive matching
+ * Note: 'async-function' removed — async alone is not an impurity marker
+ * Note: React hook markers deferred to v2
+ */
+export type MarkerType =
+  | 'await-expression'
+  | 'database-call'
+  | 'network-fetch'
+  | 'network-http'
+  | 'fs-import'
+  | 'fs-call'
+  | 'env-access'
+  | 'console-log'
+  | 'logging'
+  | 'telemetry'
+  | 'queue-enqueue'
+  | 'event-emit'
+
+/**
+ * Represents a detected impurity marker in a function
+ */
+export type ImpurityMarker = {
+  type: MarkerType
+  detail: string // e.g. "db.user.findFirst"
+  line?: number // optional line number for better reporting
+}
+
+/**
+ * Binary classification — objective, no heuristics
+ */
+export type FunctionClassification = 'pure' | 'impure'
+
+/**
+ * Derived status for UX — actionable guidance
+ */
+export type Status = 'ok' | 'review' | 'refactor'
+
+/**
+ * A function that has been classified with markers, classification, quality score, and status
+ */
+export type ClassifiedFunction = ExtractedFunction & {
+  markers: ImpurityMarker[]
+  classification: FunctionClassification
+  qualityScore: number | null // 0-100 for impure functions; null for pure
+  status: Status // derived from classification + qualityScore
+}
+
+/**
+ * Breakdown of function statuses
+ */
+export type StatusBreakdown = {
+  ok: number
+  review: number
+  refactor: number
+}
+
+/**
+ * Refactoring candidate summary for reporting
+ */
+export type RefactoringCandidate = {
+  name: string | null
+  filePath: string
+  startLine: number
+  bodyLineCount: number
+  qualityScore: number
+  markers: MarkerType[]
+}
+
+/**
+ * Score for a single file
+ */
+export type FileScore = {
+  filePath: string
+  purity: number // 0-100: pure / (pure + impure)
+  impurityQuality: number | null // 0-100: avg quality of impure functions; null if none
+  health: number // 0-100: functions with status 'ok' / total
+  pureCount: number
+  impureCount: number
+  excludedCount: number
+  statusBreakdown: StatusBreakdown
+  pureLineCount: number // total lines in pure functions
+  impureLineCount: number // total lines in impure functions
+  functions: ClassifiedFunction[]
+  refactoringCandidates: Omit<RefactoringCandidate, 'filePath'>[]
+  // Edge case flags
+  allExcluded?: boolean // true if all functions were excluded
+  typeOnly?: boolean // true if file has only type/interface/enum exports
+}
+
+/**
+ * Score for a directory
+ */
+export type DirectoryScore = {
+  dirPath: string
+  purity: number
+  impurityQuality: number | null
+  health: number
+  pureCount: number
+  impureCount: number
+  excludedCount: number
+  statusBreakdown: StatusBreakdown
+  pureLineCount: number
+  impureLineCount: number
+  fileScores: FileScore[]
+}
+
+/**
+ * Project-level score (top-level output)
+ */
+export type ProjectScore = {
+  purity: number // 0-100: percentage of pure functions
+  impurityQuality: number | null // 0-100: avg quality of impure functions
+  health: number // 0-100: percentage with status 'ok'
+  pureCount: number
+  impureCount: number
+  excludedCount: number
+  statusBreakdown: StatusBreakdown
+  pureLineCount: number
+  impureLineCount: number
+  directoryScores: DirectoryScore[]
+  timestamp: string
+  commitHash: string | null
+  // Sorted by bodyLineCount × (100 - qualityScore) descending (largest, lowest-quality first)
+  refactoringCandidates: RefactoringCandidate[]
+  // Edge case flags
+  allExcluded?: boolean // true if all functions were excluded
+  // Subset analysis metadata (when --files is used)
+  subset?: boolean // true if this is a subset analysis
+  filesGlob?: string // the glob pattern used for --files
+  // Errors encountered during analysis
+  errors?: AnalysisError[]
+}
+
+/**
+ * Error encountered during analysis
+ */
+export type AnalysisError = {
+  filePath: string
+  error: string
+}
+
+/**
+ * Configuration options for the analyzer
+ */
+export type AnalyzerConfig = {
+  tsconfigPath: string
+  filesGlob?: string
+  minHealth?: number
+  minPurity?: number
+  minQuality?: number
+  format?: 'console' | 'json' | 'summary'
+  outputPath?: string
+  quiet?: boolean
+  verbose?: boolean
+}
+
+/**
+ * Quality scoring thresholds (configurable)
+ */
+export type QualityThresholds = {
+  okThreshold: number // >= this is 'ok' (default: 70)
+  reviewThreshold: number // >= this is 'review', below is 'refactor' (default: 40)
+}
+
+/**
+ * Default quality thresholds
+ */
+export const DEFAULT_QUALITY_THRESHOLDS: QualityThresholds = {
+  okThreshold: 70,
+  reviewThreshold: 40,
+}
+
+/**
+ * Result of extracting functions from a file
+ */
+export type ExtractionResult = {
+  filePath: string
+  functions: ExtractedFunction[]
+  imports: FileImports
+  isTypeOnly: boolean
+  error?: string
+}
+
+/**
+ * Detection context passed to marker detection
+ */
+export type DetectionContext = {
+  imports: FileImports
+  pureFileImports: Set<string> // module specifiers ending in .pure
+}