fcis 0.1.0

package/TECHNICAL.md

@@ -0,0 +1,386 @@
+# FCIS Analyzer - Technical Documentation
+
+This document provides technical details for developers working on or extending the FCIS Analyzer.
+
+## Architecture Overview
+
+The FCIS Analyzer follows the Functional Core, Imperative Shell (FCIS) pattern itself:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CLI (Shell)                              │
+│                         cli.ts                                   │
+└─────────────────────────────────┬───────────────────────────────┘
+                                  │
+┌─────────────────────────────────▼───────────────────────────────┐
+│                      Analyzer (Shell)                            │
+│                      analyzer.ts                                 │
+│              Orchestrates the analysis pipeline                  │
+└───────┬─────────────────────────────────────────────────┬───────┘
+        │                                                 │
+        ▼                                                 ▼
+┌───────────────────┐                         ┌───────────────────┐
+│  Extraction       │                         │  Reporting        │
+│  (Shell)          │                         │  (Shell)          │
+│  - extractor.ts   │                         │  - report-json.ts │
+│  - extract-fns.ts │                         │  - report-console │
+└───────┬───────────┘                         └───────────────────┘
+        │                                               ▲
+        ▼                                               │
+┌─────────────────────────────────────────────────────────────────┐
+│                         PURE CORE                                │
+│  ┌─────────────┐  ┌─────────────────┐  ┌────────────────────┐  │
+│  │ Detection   │  │ Classification  │  │ Scoring            │  │
+│  │             │  │                 │  │                    │  │
+│  │ markers.ts  │  │ classifier.ts   │  │ scorer.ts          │  │
+│  │ detect-     │  │ quality-        │  │                    │  │
+│  │ markers.ts  │  │ scorer.ts       │  │                    │  │
+│  │             │  │ derive-status   │  │                    │  │
+│  └─────────────┘  └─────────────────┘  └────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Module Breakdown
+
+### Types (`types.ts`)
+
+Central type definitions shared across all modules:
+
+```typescript
+// Core extraction types
+type CallSite = {
+  expression: string      // e.g., "db.user.findFirst"
+  line: number           // relative to function start
+  isAwaited: boolean
+}
+
+type ExtractedFunction = {
+  name: string | null
+  filePath: string
+  startLine: number
+  endLine: number
+  isAsync: boolean
+  isExported: boolean
+  bodyLineCount: number
+  statementCount: number
+  hasConditionals: boolean
+  parentContext: string | null
+  callSites: CallSite[]
+  hasAwait: boolean
+  propertyAccessChains: string[]
+  kind: 'function' | 'method' | 'arrow' | 'function-expression' | 'getter' | 'setter'
+}
+
+// Marker types - strict union for exhaustive matching
+type MarkerType =
+  | 'await-expression'
+  | 'database-call'
+  | 'network-fetch'
+  | 'network-http'
+  | 'fs-import'
+  | 'fs-call'
+  | 'env-access'
+  | 'console-log'
+  | 'logging'
+  | 'telemetry'
+  | 'queue-enqueue'
+  | 'event-emit'
+
+// Classification
+type FunctionClassification = 'pure' | 'impure'
+type Status = 'ok' | 'review' | 'refactor'
+
+// Scores
+type FileScore = { ... }
+type DirectoryScore = { ... }
+type ProjectScore = { ... }
+```
+
+### Extraction Layer (Shell)
+
+**`extractor.ts`** - Loads TypeScript projects via ts-morph:
+
+```typescript
+function loadProject(options: ExtractorOptions): ExtractorResult
+function getCommitHash(): string | null
+```
+
+**`extract-functions.ts`** - Extracts function data from AST:
+
+```typescript
+function extractFunctions(sourceFile: SourceFile): ExtractedFunction[]
+function extractImports(sourceFile: SourceFile): FileImports
+function isTypeOnlyFile(sourceFile: SourceFile): boolean
+```
+
+### Detection Layer (Pure Core)
+
+**`markers.ts`** - Marker definitions and patterns:
+
+```typescript
+const MARKER_CATALOG: Record<MarkerType, MarkerDefinition>
+const DATABASE_OPERATIONS: Set<string>
+const FS_MODULES: Set<string>
+const HTTP_MODULES: Set<string>
+```
+
+**`detect-markers.ts`** - Marker detection logic:
+
+```typescript
+function detectMarkers(fn: ExtractedFunction, context: DetectionContext): ImpurityMarker[]
+function createDetectionContext(imports: FileImports): DetectionContext
+```
+
+### Classification Layer (Pure Core)
+
+**`classifier.ts`** - Binary classification:
+
+```typescript
+function classifyFunction(fn: ExtractedFunction, markers: ImpurityMarker[]): FunctionClassification
+function shouldExcludeFunction(fn: ExtractedFunction): boolean
+```
+
+**`quality-scorer.ts`** - Quality scoring for impure functions:
+
+```typescript
+function computeQualityScore(fn: ExtractedFunction, markers: ImpurityMarker[], context: DetectionContext): number
+function analyzeFunction(fn: ExtractedFunction, markers: ImpurityMarker[], context: DetectionContext): FunctionAnalysis
+```
+
+**`derive-status.ts`** - Status derivation:
+
+```typescript
+function deriveStatus(classification: FunctionClassification, qualityScore: number | null, thresholds?: QualityThresholds): Status
+```
+
+### Scoring Layer (Pure Core)
+
+**`scorer.ts`** - Metric aggregation:
+
+```typescript
+function scoreFile(filePath: string, functions: ClassifiedFunction[], isTypeOnly?: boolean): FileScore
+function scoreDirectory(dirPath: string, fileScores: FileScore[]): DirectoryScore
+function scoreProject(directoryScores: DirectoryScore[], options?: ProjectScoreOptions): ProjectScore
+```
+
+### Reporting Layer (Shell)
+
+**`report-json.ts`** - JSON output:
+
+```typescript
+function generateJsonReport(score: ProjectScore, options?: JsonReportOptions): string
+function writeJsonReport(score: ProjectScore, outputPath: string, options?: JsonReportOptions): void
+```
+
+**`report-console.ts`** - Console output:
+
+```typescript
+function printConsoleReport(score: ProjectScore, options?: { verbose?: boolean }): void
+function generateSummaryLine(score: ProjectScore): string
+```
+
+## Classification Rules
+
+### Binary Classification
+
+A function is **pure** if it has **zero** impurity markers.
+A function is **impure** if it has **one or more** impurity markers.
+
+**Important**: `async` alone does NOT make a function impure. Only actual I/O operations count.
+
+### Marker Detection Scope
+
+Markers are detected at the **function level**, not the file level:
+
+- A function is marked with `logging` only if it **calls** a logging function
+- A function is marked with `network-http` only if it **calls** an HTTP client function
+- A function is marked with `fs-call` only if it **calls** a file system function
+- File-level imports do NOT automatically taint all functions in the file
+
+This ensures pure helper functions in mixed files are correctly classified as pure.
+
+**Example**: A file that imports `@sai/logger` may contain:
+- Pure functions that never call the logger (correctly classified as pure)
+- Impure functions that call `log()` or `logger.info()` (correctly classified as impure)
+
+### Marker Detection Rules
+
+| Marker Type | Detection Pattern |
+|-------------|-------------------|
+| `await-expression` | Any `await` keyword in function body |
+| `database-call` | `db.*.findFirst`, `prisma.*.create`, etc. |
+| `network-fetch` | `fetch(...)` call |
+| `network-http` | `axios.*` call |
+| `fs-call` | `fs.readFile`, `fs.writeFile`, `readFile`, `writeFile`, etc. |
+| `env-access` | `process.env.*` property access |
+| `console-log` | `console.log`, `console.error`, etc. |
+| `logging` | `logger.*`, `log(...)` calls |
+| `telemetry` | `track*`, `analytics.*` calls |
+| `queue-enqueue` | `*.enqueue`, `queue.add` calls |
+| `event-emit` | `*.emit`, `*.dispatch` calls |
+
+## Quality Scoring
+
+Quality score (0-100) measures how well-structured an impure function is.
+
+### Positive Signals
+
+| Signal | Points | Description |
+|--------|--------|-------------|
+| Calls `.pure.ts` import | +30 | Explicit FCIS pattern |
+| Calls `plan*/derive*/compute*` | +20 | Pure naming convention |
+| I/O at start (GATHER) | +15 | Good structure |
+| I/O at end (EXECUTE) | +15 | Good structure |
+| Low complexity (≤5) | +10 | Simple orchestration |
+| Shell naming (`handle*`) | +5 | Intent signal |
+| Calls predicates (`is*/has*`) | +5 | Uses pure helpers |
+
+### Negative Signals (Penalties)
+
+| Signal | Penalty | Description |
+|--------|---------|-------------|
+| I/O interleaved | -20 | Tangled structure |
+| High complexity (>10) | -15 | Complex logic mixed with I/O |
+| Multiple I/O types | -10 | Too many responsibilities |
+| No pure function calls | -10 | All logic inline |
+| Very long (>100 lines) | -10 | God function |
+
+### Status Thresholds
+
+| Classification | Quality Score | Status |
+|---------------|---------------|--------|
+| pure | n/a | ✓ ok |
+| impure | ≥ 70 | ✓ ok |
+| impure | 40-69 | ◐ review |
+| impure | < 40 | ✗ refactor |
+
+## Metrics
+
+### Purity
+```
+purity = (pureCount / (pureCount + impureCount)) × 100
+```
+
+### Impurity Quality
+```
+impurityQuality = sum(qualityScore for impure functions) / impureCount
+```
+
+### Health
+```
+health = (functions with status 'ok') / totalFunctions × 100
+```
+
+### Refactoring Priority
+```
+priority = bodyLineCount × (100 - qualityScore)
+```
+
+Higher priority = larger, lower-quality functions (most impactful to fix).
+
+## CLI Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success, all thresholds passed |
+| 1 | Below threshold (`--min-health`, `--min-purity`, `--min-quality`) |
+| 2 | Configuration error |
+| 3 | Analysis error (zero files analyzed) |
+
+## Extending the Analyzer
+
+### Adding New Markers
+
+1. Add the marker type to the `MarkerType` union in `types.ts`
+2. Add detection logic in `detect-markers.ts`
+3. Add marker definition to `MARKER_CATALOG` in `markers.ts`
+4. Add tests in `detect-markers.test.ts`
+
+### Customizing Quality Scoring
+
+Modify `QUALITY_WEIGHTS` in `quality-scorer.ts`:
+
+```typescript
+export const QUALITY_WEIGHTS = {
+  callsPureFile: 30,
+  callsPureNamingConvention: 20,
+  // ... add or modify weights
+}
+```
+
+### Customizing Status Thresholds
+
+Pass custom thresholds to `deriveStatus`:
+
+```typescript
+const customThresholds: QualityThresholds = {
+  okThreshold: 80,      // Stricter: need 80+ for 'ok'
+  reviewThreshold: 50,  // Stricter: need 50+ for 'review'
+}
+```
+
+## Testing
+
+### Unit Tests (Pure Core)
+
+Test pure functions with direct input/output assertions:
+
+```typescript
+import { detectMarkers } from '../src/detection/detect-markers.js'
+
+it('should detect database calls', () => {
+  const fn = createTestFunction({
+    callSites: [{ expression: 'db.user.findFirst', line: 3, isAwaited: true }]
+  })
+  const markers = detectMarkers(fn, context)
+  expect(markers).toContainEqual({ type: 'database-call', ... })
+})
+```
+
+### Integration Tests
+
+Use ts-morph's in-memory file system:
+
+```typescript
+import { Project } from 'ts-morph'
+
+const project = new Project({ useInMemoryFileSystem: true })
+project.createSourceFile('/test.ts', `
+  export async function getUser(id: string) {
+    return await db.user.findFirst({ where: { id } })
+  }
+`)
+```
+
+## Performance Considerations
+
+- **Target**: Full monorepo analysis < 60 seconds
+- **Single file**: < 2 seconds
+- **Optimization**: ts-morph lazy loading, parallel file processing
+
+### Future: Caching (Post-v1)
+
+- Cache `ExtractedFunction[]` per file by content hash
+- Store in `.fcis-cache/` (gitignored)
+- Invalidate on ts-morph or fcis version change
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `ts-morph` | TypeScript AST parsing |
+| `zod` | CLI argument validation |
+| `cleye` | CLI argument parsing |
+| `chalk` | Colored console output |
+| `ts-pattern` | Pattern matching (optional) |
+
+## File Exclusions
+
+Automatically excluded from analysis:
+- `*.test.ts`, `*.spec.ts` - Test files
+- `*.d.ts` - Type declaration files
+- `*.stories.tsx` - Storybook files
+- `/node_modules/` - Dependencies
+- `/generated/` - Generated code
+- Type-only files (only types/interfaces/enums)
+- Trivial functions (< 3 statements, no conditionals)

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node