fcis 0.1.0 → 0.2.1

package/README.md

@@ -2,108 +2,238 @@
 
 **Functional Core, Imperative Shell** analyzer for TypeScript codebases.
 
-FCIS is a static analysis tool that measures how well your TypeScript code separates pure business logic from I/O and side effects. It answers the question:
+<p align="center">
+  <img src="docs/images/fc-is-submarine.webp" alt="FCIS Submarine: Keep the chaos in the waves, keep the math underwater" width="600" />
+</p>
 
-> "Can this function's logic be tested without mocking anything?"
+<p align="center"><em>Keep the chaos in the waves. Keep the math underwater.</em></p>
+
+## Philosophy
+
+FCIS is built on a simple observation: **some code is easier to trust than others.**
+
+Consider two functions:
+
+```typescript
+// Function A: Pure
+function calculateDiscount(price: number, memberYears: number): number {
+  if (memberYears >= 5) return price * 0.20
+  if (memberYears >= 2) return price * 0.10
+  return 0
+}
+
+// Function B: Impure
+async function applyDiscount(userId: string) {
+  const user = await db.user.findFirst({ where: { id: userId } })
+  const cart = await db.cart.findFirst({ where: { userId } })
+  let discount = 0
+  if (user.memberSince) {
+    const years = (Date.now() - user.memberSince.getTime()) / (365 * 24 * 60 * 60 * 1000)
+    if (years >= 5) discount = cart.total * 0.20
+    else if (years >= 2) discount = cart.total * 0.10
+  }
+  await db.cart.update({ where: { id: cart.id }, data: { discount } })
+  await sendEmail(user.email, `You saved $${discount}!`)
+}
+```
+
+**Function A** can be tested with a simple assertion: `expect(calculateDiscount(100, 5)).toBe(20)`. No mocks, no setup, no database. You can run it a thousand times in milliseconds and know exactly what it does.
+
+**Function B** requires a test database, mock email service, careful setup of user and cart records, and you still can't be sure the discount logic is correct because it's tangled up with I/O operations.
+
+This is the core insight of the **Functional Core, Imperative Shell** pattern:
+
+> Separate the code you need to **think hard about** (business logic) from the code that **talks to the outside world** (I/O). Test the thinking. Integration-test the talking.
+
+## What This Tool Measures
+
+FCIS doesn't try to eliminate impure code — **you need I/O to build useful software**. Instead, it measures:
+
+### 1. How much of your logic is testable without mocks? → **Purity**
+
+A function is **pure** if it has no I/O markers (database calls, network requests, file system access, etc.). Pure functions are trivially testable and easy to reason about.
+
+*Purity = pure functions / total functions*
+
+### 2. When you do have I/O, is it well-organized? → **Impurity Quality**
+
+Impure functions aren't bad — they're necessary. But there's a difference between:
+
+- **Well-structured:** Gathers data, calls pure functions for decisions, executes effects (GATHER → DECIDE → EXECUTE)
+- **Tangled:** Business logic interleaved with database calls, conditionals mixed with I/O, impossible to test in pieces
+
+FCIS scores impure functions from 0-100 based on structural signals. A score of 70+ means "this I/O code is well-organized."
+
+### 3. Overall: How confident can you be in this codebase? → **Health**
+
+**Health** combines purity and quality into a single number:
+
+- Pure functions are automatically "healthy" (trivially testable)
+- Impure functions with quality ≥70 are "healthy" (well-structured, integration-testable)
+- Impure functions with quality <70 need attention
+
+*Health = functions with OK status / total functions*
+
+**The goal isn't 100% purity.** A codebase with 40% purity and 90% health is better than one with 80% purity and 50% health. The first has well-organized I/O; the second has tangled messes.
+
+## The FCIS Pattern
+
+The pattern this tool encourages:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     IMPERATIVE SHELL                        │
+│                                                             │
+│   async function handleRequest(id: string) {                │
+│     // GATHER - get data from the outside world             │
+│     const user = await db.user.findFirst(...)               │
+│     const permissions = await authService.check(...)        │
+│                                                             │
+│     // DECIDE - call pure functions (testable!)             │
+│     const plan = planUserAction(user, permissions)          │
+│                                                             │
+│     // EXECUTE - write to the outside world                 │
+│     await db.audit.create({ data: plan.auditEntry })        │
+│     return plan.response                                    │
+│   }                                                         │
+└─────────────────────────────────────────────────────────────┘
+                            │
+                            ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     FUNCTIONAL CORE                         │
+│                                                             │
+│   function planUserAction(user: User, perms: Permissions) { │
+│     // Pure logic - no I/O, no side effects                 │
+│     // Easy to test: input → output                         │
+│     if (!perms.canAct) {                                    │
+│       return { allowed: false, reason: 'forbidden' }        │
+│     }                                                       │
+│     return {                                                │
+│       allowed: true,                                        │
+│       auditEntry: { userId: user.id, action: 'acted' },     │
+│       response: { success: true }                           │
+│     }                                                       │
+│   }                                                         │
+└─────────────────────────────────────────────────────────────┘
+```
 
 ## Installation
 
 ```bash
-pnpm install
-pnpm build
+npm install -g fcis
+# or
+pnpm add -g fcis
 ```
 
 ## Quick Start
 
 ```bash
 # Analyze a project
-npx fcis tsconfig.json
+fcis tsconfig.json
 
-# Analyze with health threshold (CI gate)
-npx fcis tsconfig.json --min-health 70
+# Set a health threshold for CI
+fcis tsconfig.json --min-health 70
 
-# Output JSON report
-npx fcis tsconfig.json --format json --output report.json
+# Output JSON for further processing
+fcis tsconfig.json --format json --output report.json
 
 # Analyze specific files (for pre-commit hooks)
-npx fcis tsconfig.json --files "src/services/**/*.ts"
+fcis tsconfig.json --files "src/services/**/*.ts"
 ```
 
-## What It Measures
-
-### Purity (0-100%)
-
-Percentage of functions that are **pure** — no I/O markers detected. Pure functions:
-- Take arguments and return values
-- Have no side effects
-- Can be tested without mocking
-
-### Impurity Quality (0-100)
-
-For impure functions, measures how **well-structured** the I/O code is:
-- **High (≥70):** I/O is organized, calls pure functions, follows GATHER→DECIDE→EXECUTE pattern
-- **Medium (40-69):** Some structure, room for improvement
-- **Low (<40):** Tangled code, business logic mixed with I/O
-
-### Health (0-100%)
+## Example Output
 
-Percentage of functions with status **OK** (either pure, or impure with quality ≥70).
+```
+FCIS Analysis
+═══════════════════════════════════════════════════════════
 
-## Function Classification
+Project Health: 77% ████████████████████░░░░░
+  Purity:           45% (234 pure / 520 total)
+  Impurity Quality: 68% average
 
-Every function is classified as:
+Status Breakdown:
+  ✓ OK:       312 functions (60%)  — no action needed
+  ◐ Review:    89 functions (17%)  — could be improved
+  ✗ Refactor: 119 functions (23%)  — tangled, needs work
 
-| Classification | Criteria | Testable without mocks? |
-|---------------|----------|------------------------|
-| **Pure** | No I/O markers | ✅ Yes |
-| **Impure** | Has I/O markers (await, db, fetch, fs, etc.) | ❌ No |
+Top Refactoring Candidates:
+(Sorted by impact: size × complexity)
 
-### Status Derivation
+ 1.  25/100 processOrder (150 lines)
+      /src/services/orders.ts:45
+      Markers: database-call, network-fetch, console-log
 
-| Classification | Quality Score | Status | Action |
-|---------------|---------------|--------|--------|
-| Pure | n/a | ✓ OK | None needed |
-| Impure | ≥ 70 | ✓ OK | Well-structured |
-| Impure | 40-69 | ◐ Review | Consider improving |
-| Impure | < 40 | ✗ Refactor | Prioritize cleanup |
+ 2.  32/100 handleUserUpdate (98 lines)
+      /src/services/users.ts:120
+      Markers: database-call, await-expression
+```
 
-## Impurity Markers
+## What Makes a Function Impure?
 
-The analyzer detects these I/O patterns:
+FCIS detects these I/O patterns:
 
 | Marker | Examples |
 |--------|----------|
 | `await-expression` | `await fetch()`, `await db.query()` |
 | `database-call` | `db.user.findFirst()`, `prisma.post.create()` |
 | `network-fetch` | `fetch(url)` |
-| `network-http` | `axios.get()`, imports from `axios` |
+| `network-http` | `axios.get()` |
 | `fs-call` | `fs.readFile()`, `fs.writeFile()` |
-| `fs-import` | Import from `fs`, `node:fs` |
 | `env-access` | `process.env.NODE_ENV` |
 | `console-log` | `console.log()`, `console.error()` |
-| `logging` | `logger.info()`, imports from logger |
+| `logging` | `logger.info()` |
 | `telemetry` | `trackEvent()`, `analytics.track()` |
 | `queue-enqueue` | `queue.enqueue()`, `queue.add()` |
-| `event-emit` | `emitter.emit()`, `dispatcher.dispatch()` |
+| `event-emit` | `emitter.emit()` |
+
+**Note:** `async` alone does NOT make a function impure — only actual I/O operations count.
+
+## What Makes Impure Code "High Quality"?
+
+FCIS rewards structural patterns that make impure code easier to understand and test:
+
+| Signal | Why It's Good |
+|--------|---------------|
+| Calls `.pure.ts` imports | Explicitly separates pure logic |
+| Calls `plan*/derive*/compute*` | Uses pure functions for decisions |
+| I/O at start (GATHER) | Clear data-fetching phase |
+| I/O at end (EXECUTE) | Clear effect-execution phase |
+| Low complexity | Simple orchestration |
+| Calls `is*/has*/should*` | Uses pure predicates |
+
+And penalizes patterns that make code hard to reason about:
+
+| Signal | Why It's Bad |
+|--------|--------------|
+| I/O interleaved throughout | Can't separate "what" from "how" |
+| High cyclomatic complexity | Too much logic mixed with I/O |
+| Multiple I/O types | Too many responsibilities |
+| No pure function calls | All logic is inline and untestable |
+| Very long function | God function, needs decomposition |
+
+## Compositional Scoring
+
+Inline callbacks (passed to `map`, `filter`, `forEach`, etc.) are absorbed into their parent function's score. This means:
+
+- A 301-line function with 6 callbacks counts as **1 function**, not 7
+- If a callback is impure, the parent is considered impure
+- Quality scores blend parent and children by line count
 
-**Note:** `async` alone does NOT make a function impure — only actual I/O markers count.
+This prevents gaming the metrics with lots of small callbacks while leaving a tangled parent function.
 
 ## CLI Reference
 
 ```
 fcis <tsconfig> [options]
 
-Arguments:
-  tsconfig              Path to tsconfig.json
-
 Options:
-  --json                Output JSON to stdout
-  --output, -o <file>   Write JSON report to file
   --min-health <N>      Exit code 1 if health < N (0-100)
   --min-purity <N>      Exit code 1 if purity < N (0-100)
   --min-quality <N>     Exit code 1 if impurity quality < N (0-100)
   --files, -f <glob>    Analyze only matching files
   --format <fmt>        Output: console (default), json, summary
+  --output, -o <file>   Write JSON report to file
+  --dir-depth <N>       Roll up directory metrics to depth N
   --quiet, -q           Suppress output, use exit code only
   --verbose, -v         Show per-file details
   --help                Show help
@@ -115,36 +245,9 @@ Options:
 | Code | Meaning |
 |------|---------|
 | 0 | Success, all thresholds passed |
-| 1 | Analysis completed but below threshold |
-| 2 | Configuration error (invalid options, tsconfig not found) |
-| 3 | Analysis error (no files could be analyzed) |
-
-## Example Output
-
-```
-FCIS Analysis
-═══════════════════════════════════════════════════════════
-
-Project Health: 77% ████████████████████░░░░░
-  Purity:           45% (234 pure / 520 total)
-  Impurity Quality: 68% average
-
-Status Breakdown:
-  ✓ OK:       312 functions (60%)  — no action needed
-  ◐ Review:    89 functions (17%)  — could be improved
-  ✗ Refactor: 119 functions (23%)  — tangled, needs work
-
-Top Refactoring Candidates:
-(Sorted by impact: size × complexity)
-
- 1.  25/100 processOrder (150 lines)
-      /src/services/orders.ts:45
-      Markers: database-call, network-fetch, console-log
-
- 2.  32/100 handleUserUpdate (98 lines)
-      /src/services/users.ts:120
-      Markers: database-call, await-expression
-```
+| 1 | Below threshold |
+| 2 | Configuration error |
+| 3 | Analysis error |
 
 ## CI Integration
 
@@ -152,10 +255,10 @@ Top Refactoring Candidates:
 
 ```yaml
 - name: FCIS Analysis
-  run: npx fcis tsconfig.json --min-health 70 --format summary
+  run: fcis tsconfig.json --min-health 70 --format summary
 ```
 
-### Pre-commit Hook (lint-staged)
+### Pre-commit Hook
 
 ```json
 {
@@ -165,25 +268,10 @@ Top Refactoring Candidates:
 }
 ```
 
-## The FCIS Pattern
-
-The **Functional Core, Imperative Shell** pattern separates code into:
-
-### Pure Core (Functional)
-- Business logic, calculations, validations
-- Takes data in, returns data out
-- No side effects
-- Trivially testable
+## Refactoring Example
 
-### Impure Shell (Imperative)
-- I/O operations (database, network, file system)
-- Orchestrates: GATHER data → call pure functions → EXECUTE effects
-- Thin wrapper around pure core
-- Requires integration tests
+**Before (tangled — quality score ~25):**
 
-### Example Refactoring
-
-**Before (tangled):**
 ```typescript
 async function acceptInvite(inviteId: string) {
   const invite = await db.invitation.findFirst({ where: { id: inviteId } })
@@ -191,7 +279,7 @@ async function acceptInvite(inviteId: string) {
   
   const org = await db.organization.findFirst({ where: { id: invite.orgId } })
   
-  // Business logic mixed with I/O
+  // Business logic mixed with I/O — hard to test!
   if (invite.expiresAt < new Date()) {
     await db.invitation.update({ where: { id: inviteId }, data: { status: 'expired' } })
     throw new Error('Expired')
@@ -206,10 +294,14 @@ async function acceptInvite(inviteId: string) {
 }
 ```
 
-**After (FCIS):**
+**After (FCIS pattern — quality score ~80):**
+
 ```typescript
-// Pure core - testable without mocks
-export function planAcceptInvite(invite: Invitation, org: Organization): AcceptInvitePlan {
+// PURE: Testable with simple assertions
+function planAcceptInvite(
+  invite: Invitation,
+  org: Organization
+): { action: 'accept', member: MemberData } | { action: 'reject', reason: string } {
   if (invite.expiresAt < new Date()) {
     return { action: 'reject', reason: 'expired' }
   }
@@ -218,17 +310,18 @@ export function planAcceptInvite(invite: Invitation, org: Organization): AcceptI
   }
   return {
     action: 'accept',
-    memberData: { userId: invite.userId, orgId: org.id }
+    member: { userId: invite.userId, orgId: org.id }
   }
 }
 
-// Impure shell - thin orchestration
+// IMPURE: Thin shell, clear GATHER → DECIDE → EXECUTE
 async function acceptInvite(inviteId: string) {
   // GATHER
   const invite = await db.invitation.findFirst({ where: { id: inviteId } })
+  if (!invite) throw new Error('Not found')
   const org = await db.organization.findFirst({ where: { id: invite.orgId } })
   
-  // DECIDE (pure)
+  // DECIDE
   const plan = planAcceptInvite(invite, org)
   
   // EXECUTE
@@ -236,37 +329,26 @@ async function acceptInvite(inviteId: string) {
     await db.invitation.update({ where: { id: inviteId }, data: { status: plan.reason } })
     throw new Error(plan.reason)
   }
-  
-  await db.member.create({ data: plan.memberData })
+  await db.member.create({ data: plan.member })
   await db.invitation.update({ where: { id: inviteId }, data: { status: 'accepted' } })
 }
 ```
 
-## Quality Score Signals
+The business logic (expiration check, capacity check) is now in a pure function that can be tested with simple input/output assertions. The shell just orchestrates I/O.
 
-### Positive (increase score)
-- Calls functions from `.pure.ts` files (+30)
-- Calls `plan*/derive*/compute*/transform*` functions (+20)
-- I/O concentrated at start (GATHER pattern) (+15)
-- I/O concentrated at end (EXECUTE pattern) (+15)
-- Low cyclomatic complexity (+10)
-- Shell naming convention (`handle*/fetch*/save*`) (+5)
-- Calls predicate functions (`is*/has*/should*`) (+5)
+## Limitations
 
-### Negative (decrease score)
-- I/O interleaved throughout (-20)
-- High cyclomatic complexity (-15)
-- Multiple I/O types (db + http + fs) (-10)
-- No pure function calls (-10)
-- Very long function (>100 lines) (-10)
+- Analyzes `.ts` files only (`.tsx` support planned)
+- Pattern matching is heuristic — may miss custom I/O patterns
+- Does not trace transitive purity (a function calling another function)
+- Quality weights are opinionated and tuned for specific patterns
 
-## Limitations
+## Further Reading
 
-- **v1 analyzes `.ts` files only** — `.tsx` files are deferred to v2
-- Pattern matching is heuristic-based — may miss custom I/O patterns
-- Does not analyze transitive purity (function calling another function)
-- Quality scoring weights are tuned for SchoolAI patterns
+- [TECHNICAL.md](./TECHNICAL.md) — Implementation details, scoring weights, extension points
+- [Gary Bernhardt's "Boundaries" talk](https://www.destroyallsoftware.com/talks/boundaries) — Original FCIS concept
+- [Mark Seemann's "Impureim Sandwich"](https://blog.ploeh.dk/2020/03/02/impureim-sandwich/) — Similar pattern
 
 ## License
 
-MIT
+MIT

package/TECHNICAL.md

@@ -64,11 +64,14 @@ type ExtractedFunction = {
   bodyLineCount: number
   statementCount: number
   hasConditionals: boolean
-  parentContext: string | null
+  parentContext: string | null    // class name, variable name, or HOF method name
   callSites: CallSite[]
   hasAwait: boolean
   propertyAccessChains: string[]
   kind: 'function' | 'method' | 'arrow' | 'function-expression' | 'getter' | 'setter'
+  // Compositional scoring fields
+  enclosingFunctionStartLine: number | null  // parent function's startLine, null if module-scope
+  isInlineCallback: boolean                   // true if callback to known HOF (map, filter, etc.)
 }
 
 // Marker types - strict union for exhaustive matching
@@ -77,7 +80,6 @@ type MarkerType =
   | 'database-call'
   | 'network-fetch'
   | 'network-http'
-  | 'fs-import'
   | 'fs-call'
   | 'env-access'
   | 'console-log'
@@ -374,6 +376,127 @@ project.createSourceFile('/test.ts', `
 | `chalk` | Colored console output |
 | `ts-pattern` | Pattern matching (optional) |
 
+## Directory Rollup
+
+When `--dir-depth N` is specified, directory metrics are aggregated hierarchically.
+
+### FC/IS Architecture
+
+The rollup feature follows the Functional Core / Imperative Shell pattern:
+
+- **Shell layer** (`report-console.ts`, `report-json.ts`): Converts absolute paths to relative paths using `path.relative()`
+- **Pure core** (`scorer.ts`): The `rollupDirectoriesByDepth()` function operates on already-relative paths, keeping the scoring module free of I/O dependencies
+
+### Algorithm
+
+1. Shell layer converts absolute directory paths to relative paths
+2. Pure function truncates paths to N+1 segments (e.g., depth 1 → `src/services`)
+3. Directories with the same truncated path are grouped together
+4. Metrics are aggregated using weighted averages (weighted by function count):
+   - Health = (total ok functions) / (total functions) × 100
+   - Purity = (total pure functions) / (total functions) × 100
+   - Impurity Quality = weighted average by impure function count
+5. All directories at the specified depth are shown, sorted alphabetically
+
+This provides a high-level view of codebase health by area without the noise of deeply nested leaf directories.
+
+### Edge Cases
+
+- **Depth exceeds nesting:** Directories shallower than the requested depth are shown at their actual depth
+- **Single directory:** Works correctly with a single input directory
+- **Empty directories:** Directories with no functions are excluded from aggregation
+
+### JSON Output
+
+When `--dir-depth` is used with `--json` or `--output`, the JSON includes:
+- `directoryScores` — full leaf-level data (always present)
+- `rolledUpDirectories` — aggregated data at specified depth (only when `--dir-depth` used)
+
+This is non-breaking for existing consumers.
+
+## Compositional Function Scoring
+
+FCIS uses compositional scoring to handle inline callbacks (arrow functions passed to `map`, `filter`, `forEach`, etc.). This prevents inflated function counts and diluted health scores.
+
+### Inline Callback Detection
+
+Functions are marked as inline callbacks (`isInlineCallback: true`) when passed to known higher-order functions:
+
+**Included (absorbed into parent):**
+- Array methods: `map`, `filter`, `reduce`, `forEach`, `find`, `findIndex`, `some`, `every`, `flatMap`, `sort`, `toSorted`
+- Promise methods: `then`, `catch`, `finally`
+- Timing/events: `setTimeout`, `setInterval`, `addEventListener`, `on`, `once`
+
+**Excluded (remain independent):**
+- tRPC handlers: `query`, `mutation`, `subscription`
+- Express middleware: `use`, `get`, `post`, `put`, `delete`, `patch`
+- Custom application HOFs
+
+Framework-specific handlers represent distinct behavioral units and should be scored independently.
+
+### Enclosing Function Discovery
+
+Each inline callback is linked to its enclosing function via AST upward walk:
+
+```typescript
+type ExtractedFunction = {
+  // ... other fields ...
+  enclosingFunctionStartLine: number | null  // null if module-scope
+  isInlineCallback: boolean
+}
+```
+
+Callbacks at module scope (no enclosing function) are treated as top-level functions.
+
+### Impurity Bubbling
+
+If an inline callback is impure, the enclosing function is **effectively impure**. The function's own classification remains unchanged (for drill-down), but metrics use the effective classification:
+
+```typescript
+// In scorer.ts
+function isEffectivelyImpure(entry: FunctionWithChildren): boolean {
+  if (entry.fn.classification === 'impure') return true
+  return entry.children.some(child => child.classification === 'impure')
+}
+```
+
+Markers from children are aggregated into the parent's refactoring candidate entry.
+
+### Quality Composition
+
+Parent quality is blended with impure children's quality, weighted by line count:
+
+```
+composedQuality = (parentQuality × parentOwnLines + Σ(childQuality × childLines)) / totalLines
+```
+
+Where:
+- `parentOwnLines = parent.bodyLineCount - Σ(child.bodyLineCount)` (clamped to min 1)
+- `totalLines = parentOwnLines + Σ(child.bodyLineCount)`
+
+**Example:**
+- Parent: 50 total lines, 40 own lines, quality 60
+- Child: 10 lines, quality 40
+- Composed: `(60×40 + 40×10) / 50 = 56`
+
+Pure children do not factor into the impurity quality calculation.
+
+### Function Counts
+
+Only top-level functions are counted in health/purity metrics:
+- `isInlineCallback === false`, OR
+- `isInlineCallback === true` but `enclosingFunctionStartLine === null` (module-scope)
+
+This prevents a 301-line function with 6 callbacks from being counted as 7 functions.
+
+### Line Counts
+
+Line counts no longer double-count nested callbacks. Parent `bodyLineCount` already includes nested callback lines, so only top-level functions are summed.
+
+### JSON Output
+
+All functions (including inline callbacks) remain in the JSON output with `isInlineCallback: true` for detailed analysis. The metrics reflect composed scores, but drill-down data is preserved.
+
 ## File Exclusions
 
 Automatically excluded from analysis: