fcis 0.2.0 → 0.2.1

package/README.md

@@ -2,133 +2,144 @@
 
 **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>
 
-## Installation
+## Philosophy
 
-```bash
-pnpm install
-pnpm build
-```
+FCIS is built on a simple observation: **some code is easier to trust than others.**
 
-## Quick Start
-
-```bash
-# Analyze a project
-npx fcis tsconfig.json
+Consider two functions:
 
-# Analyze with health threshold (CI gate)
-npx fcis tsconfig.json --min-health 70
-
-# Output JSON report
-npx fcis tsconfig.json --format json --output report.json
+```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
+}
 
-# Analyze specific files (for pre-commit hooks)
-npx fcis tsconfig.json --files "src/services/**/*.ts"
+// 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}!`)
+}
 ```
 
-## What It Measures
+**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.
 
-### Purity (0-100%)
+**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.
 
-Percentage of **top-level** 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
+This is the core insight of the **Functional Core, Imperative Shell** pattern:
 
-### Impurity Quality (0-100)
+> 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.
 
-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
+## What This Tool Measures
 
-### Health (0-100%)
+FCIS doesn't try to eliminate impure code — **you need I/O to build useful software**. Instead, it measures:
 
-Percentage of top-level functions with status **OK** (either pure, or impure with quality ≥70).
+### 1. How much of your logic is testable without mocks? → **Purity**
 
-### Compositional Scoring
+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.
 
-Inline callbacks (passed to `map`, `filter`, `forEach`, etc.) are **absorbed into their parent function's score** rather than counted independently. This prevents:
-- Inflated function counts (a 301-line function with 6 callbacks is 1 function, not 7)
-- Diluted health scores (callbacks can't mask a problematic parent)
-- Double-counted line counts
+*Purity = pure functions / total functions*
 
-If a callback is impure, the parent is considered effectively impure. Quality scores are blended by line count.
+### 2. When you do have I/O, is it well-organized? → **Impurity Quality**
 
-See [TECHNICAL.md](./TECHNICAL.md#compositional-function-scoring) for details.
+Impure functions aren't bad — they're necessary. But there's a difference between:
 
-## Function Classification
+- **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
 
-Every function is classified as:
+FCIS scores impure functions from 0-100 based on structural signals. A score of 70+ means "this I/O code is well-organized."
 
-| Classification | Criteria | Testable without mocks? |
-|---------------|----------|------------------------|
-| **Pure** | No I/O markers | ✅ Yes |
-| **Impure** | Has I/O markers (await, db, fetch, fs, etc.) | ❌ No |
+### 3. Overall: How confident can you be in this codebase? → **Health**
 
-### Status Derivation
+**Health** combines purity and quality into a single number:
 
-| 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 |
+- 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
 
-## Impurity Markers
+*Health = functions with OK status / total functions*
 
-The analyzer detects these I/O patterns:
+**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.
 
-| 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` |
-| `fs-call` | `fs.readFile()`, `fs.writeFile()` |
-| `env-access` | `process.env.NODE_ENV` |
-| `console-log` | `console.log()`, `console.error()` |
-| `logging` | `logger.info()`, imports from logger |
-| `telemetry` | `trackEvent()`, `analytics.track()` |
-| `queue-enqueue` | `queue.enqueue()`, `queue.add()` |
-| `event-emit` | `emitter.emit()`, `dispatcher.dispatch()` |
-
-**Note:** `async` alone does NOT make a function impure — only actual I/O markers count.
+## The FCIS Pattern
 
-## CLI Reference
+The pattern this tool encourages:
 
 ```
-fcis <tsconfig> [options]
+┌─────────────────────────────────────────────────────────────┐
+│                     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 }                           │
+│     }                                                       │
+│   }                                                         │
+└─────────────────────────────────────────────────────────────┘
+```
 
-Arguments:
-  tsconfig              Path to tsconfig.json
+## Installation
 
-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
-  --dir-depth <N>       Roll up directory metrics to depth N (e.g., 1 for top-level)
-  --quiet, -q           Suppress output, use exit code only
-  --verbose, -v         Show per-file details
-  --help                Show help
-  --version             Show version
+```bash
+npm install -g fcis
+# or
+pnpm add -g fcis
 ```
 
-### Exit Codes
+## Quick Start
 
-| 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) |
+```bash
+# Analyze a project
+fcis tsconfig.json
+
+# Set a health threshold for CI
+fcis tsconfig.json --min-health 70
+
+# Output JSON for further processing
+fcis tsconfig.json --format json --output report.json
+
+# Analyze specific files (for pre-commit hooks)
+fcis tsconfig.json --files "src/services/**/*.ts"
+```
 
 ## Example Output
 
@@ -157,29 +168,86 @@ Top Refactoring Candidates:
       Markers: database-call, await-expression
 ```
 
-### Directory Rollup
+## What Makes a Function Impure?
 
-To see aggregate metrics for top-level directories instead of leaf directories:
+FCIS detects these I/O patterns:
 
-```bash
-fcis tsconfig.json --dir-depth 1
-```
+| 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()` |
+| `fs-call` | `fs.readFile()`, `fs.writeFile()` |
+| `env-access` | `process.env.NODE_ENV` |
+| `console-log` | `console.log()`, `console.error()` |
+| `logging` | `logger.info()` |
+| `telemetry` | `trackEvent()`, `analytics.track()` |
+| `queue-enqueue` | `queue.enqueue()`, `queue.add()` |
+| `event-emit` | `emitter.emit()` |
 
-Example output:
+**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
+
+This prevents gaming the metrics with lots of small callbacks while leaving a tangled parent function.
+
+## CLI Reference
 
 ```
-Directory Breakdown (depth=1):
-────────────────────────────────────────────────────────────────────────────────
-Directory                               Health    Purity    Quality   Functions
-────────────────────────────────────────────────────────────────────────────────
-src/agents                              45%       30%       52%       12/40
-src/api                                 62%       55%       48%       28/51
-src/graph-flow                          38%       25%       41%       45/120
-src/providers                           85%       80%       72%       8/10
-src/services                            52%       40%       55%       89/171
+fcis <tsconfig> [options]
+
+Options:
+  --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
+  --version             Show version
 ```
 
-This shows ALL directories at the specified depth with aggregated metrics, providing a high-level overview of codebase health by area. When using `--dir-depth` with `--json` or `--output`, the JSON output will include a `rolledUpDirectories` field alongside the full `directoryScores`.
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success, all thresholds passed |
+| 1 | Below threshold |
+| 2 | Configuration error |
+| 3 | Analysis error |
 
 ## CI Integration
 
@@ -187,10 +255,10 @@ This shows ALL directories at the specified depth with aggregated metrics, provi
 
 ```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
 {
@@ -200,25 +268,10 @@ This shows ALL directories at the specified depth with aggregated metrics, provi
 }
 ```
 
-## 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 } })
@@ -226,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')
@@ -241,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' }
   }
@@ -253,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
@@ -271,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/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire } from 'module';
 import { cli } from 'cleye';
 import chalk from 'chalk';
 import * as fs3 from 'fs';
@@ -1912,6 +1913,8 @@ var EXIT_SUCCESS = 0;
 var EXIT_THRESHOLD_FAILED = 1;
 var EXIT_CONFIG_ERROR = 2;
 var EXIT_ANALYSIS_ERROR = 3;
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
 function handleAnalysisOutput(score, flags) {
   if (!flags.quiet) {
     if (flags.json || flags.format === "json") {
@@ -1963,7 +1966,7 @@ function ensureOutputDirectory(outputPath) {
 }
 var argv = cli({
   name: "fcis",
-  version: "0.1.0",
+  version: pkg.version,
   flags: {
     json: {
       type: Boolean,