fcis 0.1.0

package/.plans/002-fcis-analyzer-improvements.md

@@ -0,0 +1,205 @@
+# Plan 002: FCIS Analyzer Improvements
+
+## Background
+
+Plan 001 implemented the FCIS (Functional Core, Imperative Shell) analyzer for TypeScript codebases. After running the analyzer against the SchoolAI monorepo (`apps/web` and `packages/`), several issues were identified that affect the accuracy and usability of the tool.
+
+Key findings from baseline analysis:
+- **apps/web**: 48% health, 38% purity, 52% impurity quality (2002 functions analyzed)
+- **packages/utils**: 86% health, 85% purity (65 functions analyzed)
+- **server/services**: 20% health, 14% purity, 47% impurity quality (high-priority refactoring area)
+
+## Problem Statement
+
+Three issues undermine the tool's usefulness:
+
+1. **File-level import tainting (CRITICAL)**: Pure functions like `shouldModerate`, `shouldSendRedAlertEmail`, and `getRedAlertType` in `moderation.ts` are incorrectly classified as impure because the file imports `@sai/logger`, even though these functions never call the logger. This false positive problem undermines trust in the tool's signal.
+
+2. **Anonymous function names**: Many refactoring candidates appear as `<anonymous>` because they are arrow functions assigned to variables. This makes it harder for developers to locate and prioritize functions.
+
+3. **tsconfig with comments fails parsing**: TypeScript projects commonly use comments in `tsconfig.json`, but the current JSON parser fails on these files, preventing analysis of the ai-platform codebase.
+
+## Success Criteria
+
+1. Pure functions in files that import loggers/analytics but don't use them are classified as **pure** (not impure)
+2. Arrow functions assigned to variables display the variable name (e.g., `handleSubmit` instead of `<anonymous>`)
+3. tsconfig.json files with comments parse successfully
+4. Re-run baseline analysis against `moderation.ts` — `shouldModerate`, `shouldSendRedAlertEmail`, `getRedAlertType` should all classify as **pure**
+5. Re-run baseline analysis against `ai-platform/apps/server` — should complete without parser errors
+
+## The Gap
+
+| Issue | Current Behavior | Expected Behavior |
+|-------|------------------|-------------------|
+| Logger import tainting | Any file importing `@sai/logger` marks ALL functions as having `logging` marker | Only functions that CALL `log()`, `logger.*`, etc. should get the marker |
+| Anonymous function names | Arrow functions extracted with `name: null` | Should use the variable name from the declaration |
+| tsconfig with comments | `JSON.parse()` throws on comments | Should strip comments or use JSON5/jsonc parser |
+
+## Phases and Tasks
+
+### Phase 1: Fix File-Level Import Tainting ✅
+
+This is the highest-impact fix. Currently, the `detectLoggingMarkers` function in `detect-markers.ts` adds a marker for all functions if the file imports from a logger module.
+
+- Remove file-level import marker logic from `detectLoggingMarkers` ✅
+- Keep only call-site-based detection for logging (function must actually call `logger.*`, `log()`, etc.) ✅
+- Apply same fix to HTTP module detection in `detectNetworkMarkers` — only flag if function uses the import ✅
+- Apply same fix to FS module detection in `detectFileSystemMarkers` — only flag if function uses the import ✅
+- Write unit tests verifying pure functions in files with logger imports remain pure ✅
+
+### Phase 2: Improve Arrow Function Naming ✅
+
+Arrow functions assigned to variables should display the variable name.
+
+- In `extract-functions.ts`, when extracting arrow functions from variable declarations, already capture `varName` as `parentContext` ✅
+- Modify to also set `name` to `varName` when the arrow function has no intrinsic name ✅
+- Update tests to verify arrow function variable names are captured ✅
+
+### Phase 2b: Extract Inline Arrow Functions ✅ (Additional Fix)
+
+Arrow functions passed as arguments (e.g., tRPC handlers, callbacks) were not being extracted.
+
+- Add extraction of ALL arrow functions in file, not just those assigned to variables ✅
+- Infer parent context from call expression (e.g., `.mutation()` -> name is "mutation") ✅
+- Use deduplication to avoid extracting the same function twice ✅
+- Write tests for inline arrow function extraction ✅
+
+This fix increased function detection from 829 to 1366 in `apps/web/src/server/**/*.ts`.
+
+### Phase 3: Handle tsconfig.json with Comments ✅
+
+- Add `stripJsonComments` function (regex-based implementation) ✅
+- In `extractor.ts`, strip comments from tsconfig content before parsing ✅
+- Write test verifying tsconfig with comments parses successfully ✅
+
+### Phase 4: Validation and Documentation ✅
+
+- Re-run analysis on `moderation.ts` and verify pure functions are classified correctly ✅
+- Run analysis on `ai-platform/apps/server` and verify it completes ✅
+- Update TECHNICAL.md with notes on marker detection behavior ✅
+- Update README.md examples if needed ✅ (no changes needed)
+
+## Tests
+
+### Unit Tests
+
+**`detect-markers.test.ts`** — Add tests for fixed import behavior:
+
+```typescript
+describe('logging detection', () => {
+  it('should NOT mark function as impure just because file imports logger', () => {
+    const fn = createTestFunction({
+      callSites: [{ expression: 'Object.entries', line: 2, isAwaited: false }],
+    })
+    const context = createTestContext([
+      { moduleSpecifier: '@sai/logger', namedImports: ['log'] },
+    ])
+    
+    const markers = detectMarkers(fn, context)
+    expect(markers.filter(m => m.type === 'logging')).toHaveLength(0)
+  })
+
+  it('should mark function as impure when it calls log()', () => {
+    const fn = createTestFunction({
+      callSites: [{ expression: 'log', line: 5, isAwaited: false }],
+    })
+    const context = createTestContext([
+      { moduleSpecifier: '@sai/logger', namedImports: ['log'] },
+    ])
+    
+    const markers = detectMarkers(fn, context)
+    expect(markers).toContainEqual(expect.objectContaining({ type: 'logging' }))
+  })
+})
+```
+
+**`extract-functions.test.ts`** — Add test for arrow function naming:
+
+```typescript
+it('should use variable name for arrow functions', () => {
+  const project = new Project({ useInMemoryFileSystem: true })
+  const sf = project.createSourceFile('/test.ts', `
+    export const handleSubmit = async (data: FormData) => {
+      const result = await processData(data)
+      return result
+    }
+  `)
+  
+  const functions = extractFunctions(sf)
+  expect(functions[0]?.name).toBe('handleSubmit')
+})
+```
+
+**`extractor.test.ts`** — Add test for tsconfig with comments:
+
+```typescript
+it('should parse tsconfig with comments', () => {
+  // Create temp tsconfig with comments
+  const content = `{
+    // This is a comment
+    "compilerOptions": {
+      "target": "es2022" // inline comment
+    }
+  }`
+  
+  // Verify it doesn't throw
+  expect(() => loadProject({ tsconfigPath: tempPath })).not.toThrow()
+})
+```
+
+### Integration Test
+
+Re-validate against real codebase files:
+
+- `apps/web/src/server/services/moderation.ts` — `shouldModerate`, `shouldSendRedAlertEmail`, `getRedAlertType` should be **pure**
+- `ai-platform/apps/server/tsconfig.json` — should parse without errors
+
+## Transitive Effect Analysis
+
+1. **Marker Detection → Classification → Scoring**: Fixing marker detection directly affects classification (fewer false positives → higher purity scores), which affects file/directory/project scores. All downstream calculations will show improved metrics.
+
+2. **Pure function files**: Files that currently show 0% purity due to logger imports (like `moderation.ts`) will show mixed purity, revealing the actual pure helpers within.
+
+3. **CLI output**: Refactoring candidate lists may change as previously-flagged pure functions drop off the list.
+
+4. **Existing tests**: Current unit tests mock extracted function data directly, so they won't break. Integration tests that rely on specific marker counts may need adjustment.
+
+## Resources for Implementation
+
+**Files to modify:**
+
+- `fcis/src/detection/detect-markers.ts` — Lines 266-295 (`detectLoggingMarkers` and import-based logic)
+- `fcis/src/detection/detect-markers.ts` — Lines 202-226 (`detectNetworkMarkers` HTTP module import logic)
+- `fcis/src/extraction/extract-functions.ts` — Lines 75-95 (arrow function extraction)
+- `fcis/src/extraction/extractor.ts` — Lines 38-48 (tsconfig parsing)
+
+**Reference files:**
+
+- `apps/web/src/server/services/moderation.ts` — Example of file with pure functions and logger import
+- `ai-platform/apps/server/tsconfig.json` — Example of tsconfig with comments
+
+**Dependencies to add:**
+
+- `strip-json-comments` (or use regex-based stripping)
+
+## Documentation Updates
+
+### TECHNICAL.md
+
+Add section clarifying marker detection behavior:
+
+```markdown
+### 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
+- File-level imports do NOT automatically taint all functions in the file
+
+This ensures pure helper functions in mixed files are correctly classified.
+```
+
+### README.md
+
+No changes needed — the public API and usage remain the same.

package/README.md

@@ -0,0 +1,272 @@
+# FCIS Analyzer
+
+**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:
+
+> "Can this function's logic be tested without mocking anything?"
+
+## Installation
+
+```bash
+pnpm install
+pnpm build
+```
+
+## Quick Start
+
+```bash
+# Analyze a project
+npx fcis tsconfig.json
+
+# 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
+
+# Analyze specific files (for pre-commit hooks)
+npx 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%)
+
+Percentage of functions with status **OK** (either pure, or impure with quality ≥70).
+
+## Function Classification
+
+Every function is classified as:
+
+| Classification | Criteria | Testable without mocks? |
+|---------------|----------|------------------------|
+| **Pure** | No I/O markers | ✅ Yes |
+| **Impure** | Has I/O markers (await, db, fetch, fs, etc.) | ❌ No |
+
+### Status Derivation
+
+| 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 |
+
+## Impurity Markers
+
+The analyzer 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` |
+| `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 |
+| `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.
+
+## 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
+  --quiet, -q           Suppress output, use exit code only
+  --verbose, -v         Show per-file details
+  --help                Show help
+  --version             Show version
+```
+
+### Exit Codes
+
+| 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
+```
+
+## CI Integration
+
+### GitHub Actions
+
+```yaml
+- name: FCIS Analysis
+  run: npx fcis tsconfig.json --min-health 70 --format summary
+```
+
+### Pre-commit Hook (lint-staged)
+
+```json
+{
+  "lint-staged": {
+    "*.ts": ["fcis tsconfig.json --files"]
+  }
+}
+```
+
+## 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
+
+### 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
+
+### Example Refactoring
+
+**Before (tangled):**
+```typescript
+async function acceptInvite(inviteId: string) {
+  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 } })
+  
+  // Business logic mixed with I/O
+  if (invite.expiresAt < new Date()) {
+    await db.invitation.update({ where: { id: inviteId }, data: { status: 'expired' } })
+    throw new Error('Expired')
+  }
+  
+  if (org.memberCount >= org.maxMembers) {
+    throw new Error('Org full')
+  }
+  
+  await db.member.create({ data: { userId: invite.userId, orgId: org.id } })
+  await db.invitation.update({ where: { id: inviteId }, data: { status: 'accepted' } })
+}
+```
+
+**After (FCIS):**
+```typescript
+// Pure core - testable without mocks
+export function planAcceptInvite(invite: Invitation, org: Organization): AcceptInvitePlan {
+  if (invite.expiresAt < new Date()) {
+    return { action: 'reject', reason: 'expired' }
+  }
+  if (org.memberCount >= org.maxMembers) {
+    return { action: 'reject', reason: 'org-full' }
+  }
+  return {
+    action: 'accept',
+    memberData: { userId: invite.userId, orgId: org.id }
+  }
+}
+
+// Impure shell - thin orchestration
+async function acceptInvite(inviteId: string) {
+  // GATHER
+  const invite = await db.invitation.findFirst({ where: { id: inviteId } })
+  const org = await db.organization.findFirst({ where: { id: invite.orgId } })
+  
+  // DECIDE (pure)
+  const plan = planAcceptInvite(invite, org)
+  
+  // EXECUTE
+  if (plan.action === 'reject') {
+    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.invitation.update({ where: { id: inviteId }, data: { status: 'accepted' } })
+}
+```
+
+## Quality Score Signals
+
+### 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)
+
+### 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)
+
+## Limitations
+
+- **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
+
+## License
+
+MIT