fcis 0.1.0

package/.plans/001-fcis-analyzer.md

@@ -0,0 +1,832 @@
+# Plan 001: FCIS Analyzer
+
+## Revision History
+
+**Rev 4** — Scope focused on `.ts` files; React/TSX deferred to v2:
+
+| # | Issue | Fix |
+|---|-------|-----|
+| 12 | React analysis adds complexity | **Deferred to v2:** Frontend component analysis moved to Addendum; v1 focuses on `.ts` files only |
+| 11 | "Shell" classification conflates structure and quality | **Major restructure:** Binary classification (`pure`/`impure`) + quality score (0–100) for impure functions + derived status (`ok`/`review`/`refactor`) for UX |
+| 10 | `async` false-positives | `async` alone does NOT make a function impure; only actual I/O markers count |
+| 9 | `callExpressions` loses position context | Replaced with `CallSite[]` containing `expression`, `line`, and `isAwaited` |
+| 8 | Engineering improvements | Added: strict marker types, input validation, error handling strategy, edge case handling, library recommendations |
+| 7 | CLI not linter-ready | Expanded Phase 7 with exit codes, file targeting, output formats, performance targets, CI examples |
+| 6 | Real data validation comes last | Added early validation spike in Phase 2 to inform marker design |
+
+---
+
+## Background
+
+**Functional Core, Imperative Shell (FCIS)** is an architectural pattern that separates pure business logic (the core) from I/O and side effects (the shell). When applied well, business logic becomes trivially testable — no mocks, no setup, just input/output assertions. The shell becomes thin orchestration: gather data, call pure functions, execute effects.
+
+The SchoolAI codebase has begun adopting this pattern in isolated areas:
+
+- `apps/web/src/server/services/organizations.pure.ts` — a `planAcceptInvite()` pure decision function
+- `apps/web/src/hooks/useSettingsRoutes.ts` — `deriveSettingsPageRoutes()` / `deriveOrgMenuRoutes()` pure derivations with hook shells
+- `ai-platform/apps/server/src/v1/blueprints/nodes/llm-v2/prepare-provider-request.ts` — pure provider request transformation
+
+However, the vast majority of service code interleaves business logic with database calls, HTTP requests, and other I/O. There is no way to measure adherence, track progress, or identify refactoring targets.
+
+No existing tool in the TypeScript ecosystem measures FCIS adherence. Tools like `code-health-meter` (Maintainability Index, Cyclomatic Complexity) and `cognitive-complexity-ts` measure code complexity, not structural separation of logic from I/O. Two abandoned ESLint plugins (`eslint-plugin-purecheck`, `eslint-plugin-pure-function`) attempted to enforce purity but are unmaintained and predate modern TypeScript.
+
+## Problem Statement
+
+We need a static analysis tool that answers, for any TypeScript function:
+
+> **"Can this function's logic be tested without mocking anything?"**
+
+And aggregates that answer into a score at function, file, directory, and project levels — trackable over time across git history.
+
+## Success Criteria
+
+1. Analyze `.ts` files using the TypeScript compiler (via ts-morph) — not regex. **Note:** `.tsx` files are deferred to v2.
+2. Classify every function as **pure** or **impure** (binary, objective)
+3. Compute a **quality score** (0–100) for impure functions measuring structural quality
+4. Derive a **status** (`ok` / `review` / `refactor`) for developer UX
+5. Produce metrics at function, file, directory, and project levels:
+   - **Purity:** percentage of pure functions
+   - **Impurity Quality:** average quality score of impure functions
+   - **Project Health:** percentage of functions with status `ok`
+6. Generate JSON output suitable for storage, diffing, and trend analysis
+7. Generate human-readable console output with refactoring candidates
+8. Run against the SchoolAI monorepo (`.ts` files) and produce a meaningful baseline report
+9. The tool itself follows FCIS: pure core for detection/classification/scoring, shell only for I/O
+
+## The Gap
+
+- No measurement exists today — the team cannot answer "what percentage of our business logic is testable without mocking?"
+- Existing FCIS implementations are isolated experiments, not tracked
+- Service files like `organizations.ts` (2300+ lines, 1 pure function extracted of ~50 total) represent the dominant pattern
+- There is no convention enforcement or CI feedback loop
+
+## Phases and Tasks
+
+### Phase 1: Project Scaffolding 🔴
+
+- Set up `fcis/` as a standalone TypeScript package with `tsup` for build 🔴
+- Add dependencies (from npm, not vendored): 🔴
+  - `ts-morph` — AST parsing and analysis
+  - `zod` — CLI argument validation and config schema
+  - `cleye` — typed CLI argument parsing with auto-generated help
+  - `chalk` — colored console output
+- Add dev dependencies: 🔴
+  - `vitest` — test runner with snapshot support
+  - `ts-pattern` — exhaustive pattern matching for classification logic (optional but recommended)
+- Configure `tsconfig.json` targeting ES2022/Node with strict mode 🔴
+- Establish directory structure mirroring FCIS architecture (see Architecture section) 🔴
+- Create `README.md` and `TECHNICAL.md` 🔴
+
+### Phase 2: AST Extraction Layer 🔴
+
+- Implement `extractor.ts` (shell): load a `Project` from a tsconfig path, enumerate `.ts` source files (exclude `.tsx` for v1) 🔴
+- Implement `extract-functions.ts` (shell): for each source file, extract all function-like nodes into a normalized `ExtractedFunction` structure 🔴
+- Handle all function forms: `FunctionDeclaration`, `MethodDeclaration`, `ArrowFunction`, `FunctionExpression`, `GetAccessorDeclaration`, `SetAccessorDeclaration` 🔴
+- Extract per-function: name, file path, start/end lines, isAsync, isExported, body text length, parent context (class name, variable name) 🔴
+- Extract per-function: all call sites with position and await context (see `CallSite` type), all `PropertyAccessExpression` chains 🔴
+- Extract per-file: all `ImportDeclaration` module specifiers and named imports 🔴
+- Write integration test: feed a multi-function `.ts` string to ts-morph in-memory, verify extraction output 🔴
+- **Early validation spike:** Run extraction against 5–10 representative `.ts` files from the SchoolAI codebase and document observed patterns 🔴
+  - Target files: `organizations.pure.ts`, `organizations.ts`, `moderation.ts`, `students.ts`, `chat.ts`, `prepare-provider-request.ts`
+  - Document: call expression formats (e.g., `db.user.findFirst` vs `({ db }) => db.user.findFirst`), import styles
+  - Use findings to inform Phase 3 marker design — adjust detection rules BEFORE implementing them
+
+### Phase 3: Impurity Marker Detection 🔴
+
+This is the pure core of the analyzer — all functions in this phase take data in and return data out with no I/O.
+
+- Define `ImpurityMarker` type with **strict string literal union** for `type` field (see Critical Type Declarations) 🔴
+- Define marker catalog in `markers.ts` as a **data structure**, not hardcoded logic — enables extensibility 🔴
+- Implement `detect-markers.ts`: given an `ExtractedFunction` and file-level imports, return `ImpurityMarker[]` 🔴
+- Marker categories and detection rules: 🔴
+
+  **Async/Await**
+  - `async` keyword on function → **NOT a marker** (async alone is just a calling convention; does not make a function impure)
+  - `await` expression in body → marker `await-expression` (indicates I/O suspension point)
+  - **Classification rule:** A function is impure if it has ANY I/O marker. `async` without `await` and without other I/O markers is **pure**.
+
+  **Database**
+  - Call matching `db.<entity>.<operation>` or `prisma.<entity>.<operation>` where operation ∈ {`findFirst`, `findMany`, `findUnique`, `create`, `update`, `delete`, `upsert`, `aggregate`, `count`, `groupBy`} → marker `database-call`
+
+  **Network**
+  - Call to `fetch(` → marker `network-fetch`
+  - Import from `axios`, `node-fetch`, or call to `axios.*` → marker `network-http`
+
+  **File System**
+  - Import from `fs`, `node:fs`, `fs/promises`, `node:fs/promises` → marker `fs-import`
+  - Call matching `fs.<operation>` → marker `fs-call`
+
+  **Environment**
+  - Property access `process.env.*` → marker `env-access`
+
+  **Logging/Telemetry**
+  - Call matching `console.(log|error|warn|info)` → marker `console-log`
+  - Call matching `logger.*` or `log(` (from `@sai/logger`) → marker `logging`
+  - Calls to analytics/tracking functions → marker `telemetry`
+
+  **Queue/Event**
+  - Call matching `*.enqueue(` → marker `queue-enqueue`
+  - Call matching `*.emit(` → marker `event-emit`
+
+- Write unit tests for each marker category: provide `ExtractedFunction` data, assert correct markers returned 🔴
+
+#### Error Handling in Extraction 🔴
+
+- Files that fail to parse (syntax errors, encoding issues) are logged and **skipped** — do not fail the entire analysis
+- Collect parse errors with file path and error message
+- Continue analysis with remaining files
+- Exit code 3 only if **zero files** could be analyzed successfully
+- The JSON output includes an `errors: { filePath: string, error: string }[]` array
+
+### Phase 4: Function Classification & Quality Scoring 🔴
+
+Pure core — classifies functions and computes quality scores.
+
+#### Binary Classification 🔴
+
+- Implement `classifier.ts`: given an `ExtractedFunction` with its `ImpurityMarker[]`, return a `FunctionClassification` 🔴
+- Classification is **binary and objective**: 🔴
+
+  **Pure**: Zero I/O markers. Function takes arguments and returns values with no side effects. Note: `async` without `await` (and without other I/O markers) is still **pure**.
+
+  **Impure**: Has one or more I/O markers (`await-expression`, `database-call`, `network-fetch`, `fs-call`, etc.). This function requires mocking to test.
+
+#### Quality Score for Impure Functions 🔴
+
+- Implement `quality-scorer.ts`: given an impure `ClassifiedFunction`, compute a quality score 0–100 🔴
+- Quality score measures **how well-structured** the impurity is, not whether it exists
+- Quality signals (additive, max 100): 🔴
+
+  | Signal | Points | Rationale |
+  |--------|--------|-----------|
+  | Calls a function from `.pure.ts` file | +30 | Explicit FCIS pattern |
+  | Calls `plan*/derive*/compute*/calculate*/transform*` function | +20 | Strong pure naming convention |
+  | I/O calls concentrated at start of function (GATHER pattern) | +15 | Good structure |
+  | I/O calls concentrated at end of function (EXECUTE pattern) | +15 | Good structure |
+  | Low cyclomatic complexity (≤ 5) | +10 | Simple orchestration |
+  | Function name matches shell conventions (`handle*/fetch*/save*/send*`) | +5 | Intent signal |
+  | Calls predicate functions (`is*/has*/should*`) | +5 | Uses pure helpers |
+
+- Quality penalties (subtractive): 🔴
+
+  | Signal | Penalty | Rationale |
+  |--------|---------|-----------|
+  | I/O calls interleaved throughout function body | -20 | Tangled structure |
+  | High cyclomatic complexity (> 10) | -15 | Complex logic mixed with I/O |
+  | Multiple I/O types (db + http + fs in same function) | -10 | Too many responsibilities |
+  | No pure function calls at all | -10 | All logic is inline |
+  | Very long function (> 100 lines) | -10 | God function |
+
+- Quality score is clamped to 0–100 🔴
+
+#### Derived Status for UX 🔴
+
+- Implement `derive-status.ts`: given classification and quality score, return a `Status` 🔴
+- Status provides actionable guidance for developers: 🔴
+
+  | Classification | Quality Score | Status | Developer Action |
+  |---------------|---------------|--------|------------------|
+  | pure | n/a | ✓ `ok` | None — testable without mocks |
+  | impure | ≥ 70 | ✓ `ok` | None — well-structured, mocks are manageable |
+  | impure | 40–69 | ◐ `review` | Consider improving if touching this code |
+  | impure | < 40 | ✗ `refactor` | Tangled; prioritize cleanup |
+
+- Status thresholds are configurable (can be adjusted based on team standards) 🔴
+
+#### File and Function Exclusions 🔴
+
+- Implement file-level exclusions: 🔴
+  - Files matching `*.test.ts`, `*.spec.ts`, `*.stories.tsx` → excluded from analysis
+  - Files matching `*.d.ts` → excluded
+  - Files in `/generated/`, `/node_modules/` → excluded
+  - Type-only files (only `type`, `interface`, `enum` exports, no function bodies) → excluded, flagged as `typeOnly`
+
+- Implement trivial function exclusion: functions with < 3 statements and no conditionals → excluded from scoring 🔴
+
+- Write unit tests: 🔴
+  - Classification: provide function data with various marker combinations, assert correct pure/impure
+  - Quality scoring: provide impure functions with various structural patterns, assert expected scores
+  - Status derivation: verify thresholds produce correct status
+
+### Phase 5: Scoring Engine 🔴
+
+Pure core — aggregates classifications and quality scores into project metrics.
+
+- Implement `scorer.ts` with the following pure functions: 🔴
+
+  `scoreFile(functions: ClassifiedFunction[]): FileScore` — computes:
+  - **Purity:** `pure / (pure + impure)` — percentage of functions testable without mocking
+  - **Impurity Quality:** average quality score of impure functions
+  - **Health:** `(pure + impure with quality ≥ 70) / total` — percentage of functions with status `ok`
+
+  `scoreDirectory(fileScores: FileScore[]): DirectoryScore` — weighted average by function count
+
+  `scoreProject(directoryScores: DirectoryScore[]): ProjectScore` — weighted average by function count
+
+- Each score includes: 🔴
+  - `purity`: 0–100 (percentage of pure functions)
+  - `impurityQuality`: 0–100 (average quality of impure functions; null if no impure functions)
+  - `health`: 0–100 (percentage of functions with status `ok`)
+  - `pureCount`, `impureCount`, `excludedCount`
+  - `statusBreakdown`: `{ ok: number, review: number, refactor: number }`
+  - `refactoringCandidates`: list of impure functions with status `refactor`, **sorted by `bodyLineCount × (100 - qualityScore)` descending**
+
+- **Diagnostic insights:** 🔴
+  - High purity + low impurity quality = "Most code is pure, but the impure code is tangled"
+  - Low purity + high impurity quality = "Lots of I/O, but it's well-structured"
+  - Low purity + low impurity quality = "Significant technical debt in I/O code"
+
+- **Edge case handling:** 🔴
+  - If all functions are excluded, health is `100` with flag `allExcluded: true`
+  - Type-only files get `health: 100` with flag `typeOnly: true`
+  - If no impure functions, `impurityQuality` is `null` (not 0 or 100)
+  - Division by zero is never possible due to these rules
+
+- Write unit tests: provide classification arrays with quality scores, assert correct metric computation, including edge cases (empty files, all-pure, all-impure, all-excluded) 🔴
+
+### Phase 6: Reporting 🔴
+
+Shell layer — formats and outputs results.
+
+- Implement `report-json.ts`: serialize full analysis to JSON (for storage and diffing) 🔴
+- Implement `report-console.ts`: produce human-readable CLI output including: 🔴
+
+  **Top-level summary:**
+  ```
+  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
+  ```
+
+  - Per-directory breakdown sorted by health (ascending — worst first)
+  - Top 10 refactoring candidates, **sorted by `bodyLineCount × (100 - qualityScore)` descending** (surfaces large, low-quality functions first)
+  - Summary counts: pure / impure / excluded
+  - Quality distribution: histogram or percentile breakdown of impure function quality scores
+- JSON schema includes a `timestamp` and `commitHash` field for historical tracking 🔴
+
+### Phase 7: CLI Entry Point 🔴
+
+Build a CLI suitable for running alongside linters (ESLint, TypeScript) in CI pipelines and pre-commit hooks.
+
+- Implement `cli.ts` using `commander` or simple `process.argv` parsing 🔴
+
+#### Commands and Options 🔴
+
+```
+fcis analyze <path-to-tsconfig> [options]
+
+Options:
+  --json                    Output JSON to stdout (for piping/parsing)
+  --output <file>           Write JSON report to file
+  --min-health <N>          Exit with code 1 if project health < N (CI gate, default metric)
+  --min-purity <N>          Exit with code 1 if purity < N
+  --min-quality <N>         Exit with code 1 if impurity quality < N
+  --files <glob>            Analyze only files matching glob (for incremental/pre-commit)
+  --format <fmt>            Output format: console (default), json, summary
+  --quiet                   Suppress all output except errors; rely on exit code
+  --verbose                 Show per-file scores and all classified functions
+  --no-frontend             Skip frontend component analysis (faster for backend-only)
+```
+
+#### Input Validation 🔴
+
+Validate CLI inputs using zod schemas:
+- `--min-health` must be a number 0–100; invalid → exit 2 with message
+- `--min-purity` must be a number 0–100; invalid → exit 2 with message
+- `--min-quality` must be a number 0–100; invalid → exit 2 with message
+- `<path-to-tsconfig>` must exist and be a valid JSON file; invalid → exit 2 with message
+- `--files` glob must be a valid glob pattern; invalid → exit 2 with message
+- `--output` directory must exist (or be creatable); invalid → exit 2 with message
+
+Provide clear, actionable error messages for validation failures.
+
+#### Exit Codes 🔴
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success, all thresholds passed |
+| 1 | Analysis completed but below threshold (`--min-health`, `--min-purity`, or `--min-quality`) |
+| 2 | Configuration error (tsconfig not found, invalid options, validation failure) |
+| 3 | Analysis error (zero files could be analyzed — all files had parse errors) |
+
+#### File Targeting 🔴
+
+Support analyzing a subset of files for faster feedback:
+
+```bash
+# Analyze only changed files (useful for pre-commit)
+fcis analyze tsconfig.json --files "src/services/organizations.ts"
+
+# Analyze a directory
+fcis analyze tsconfig.json --files "src/components/**/*.tsx"
+```
+
+When `--files` is used:
+- Only matching files are **extracted and classified**
+- Imports from non-matching files are still resolved for `.pure.ts` detection (import graph is still walked)
+- Score represents **only the subset**, not the whole project
+- JSON output includes `"subset": true` and `"filesGlob": "<pattern>"`
+- Useful for pre-commit hooks and editor integration
+- **Note:** Subset scores are not directly comparable to full-project scores
+
+#### Output Formats 🔴
+
+- **console** (default): Human-readable with colors, visual bars, refactoring candidates
+- **json**: Full analysis result (same as `--json`)
+- **summary**: Single-line output suitable for commit messages or PR comments
+  - Example: `FCIS Health: 77% | Purity: 45% | Impurity Quality: 68%`
+
+#### Performance Target 🔴
+
+- Full monorepo analysis: < 60 seconds
+- Single file analysis: < 2 seconds
+- Suitable for pre-commit hooks with `--files` targeting
+
+#### Caching (Post-v1) 🔴
+
+For v1, run full extraction on every invocation. Post-v1 optimization:
+- Cache `ExtractedFunction[]` per file, keyed by file content hash
+- Store cache in `.fcis-cache/` directory (gitignored)
+- On subsequent runs, only re-extract files whose content hash changed
+- Add `--cache` (default: on) and `--no-cache` flags
+- Cache invalidation: ts-morph version change, fcis version change
+
+#### CI Integration Examples 🔴
+
+**GitHub Actions:**
+```yaml
+- name: FCIS Analysis
+  run: npx fcis analyze tsconfig.json --min-health 70 --format summary
+```
+
+**Pre-commit hook (with lint-staged):**
+```json
+{
+  "lint-staged": {
+    "*.{ts,tsx}": ["fcis analyze tsconfig.json --files", "eslint --fix"]
+  }
+}
+```
+
+**Turborepo task:**
+```json
+{
+  "pipeline": {
+    "fcis": {
+      "inputs": ["src/**/*.ts", "src/**/*.tsx"],
+      "outputs": [".fcis-report.json"]
+    }
+  }
+}
+```
+
+- Wire up: load project → extract → detect → classify → score → report 🔴
+
+### Phase 8: Baseline Analysis 🔴
+
+**Note:** The Phase 2 early validation spike should have already informed marker design. This phase is full-scale validation, not discovery. Major heuristic changes at this point indicate the spike was insufficient.
+
+- Run analyzer against the SchoolAI monorepo (`apps/web/src/`, `ai-platform/`, `packages/`) 🔴
+- Validate results against known patterns: 🔴
+  - `organizations.pure.ts` functions should classify as **pure**
+  - `planAcceptInvite` should classify as **pure**
+  - `acceptInvite` in `organizations.ts` should classify as **impure** with **high quality score** (≥70, calls pure function)
+  - `deriveSettingsPageRoutes` should classify as **pure**
+  - `moderateStudentMessages` should classify as **impure** with **low quality score** (<40, tangled)
+  - `shouldModerate`, `shouldSendRedAlertEmail`, `getRedAlertType` should classify as **pure**
+  - `prepareProviderRequest` should classify as **pure**
+- Fine-tune quality scoring weights based on observed patterns (expect minor adjustments) 🔴
+- Verify metrics produce meaningful differentiation:
+  - Check that low impurity quality correlates with files developers find painful
+  - Verify refactoring candidates list surfaces high-value targets
+  - Validate status thresholds feel right (adjust 70/40 if needed)
+- Save baseline JSON report 🔴
+
+## Architecture
+
+```
+fcis/
+├── src/
+│   ├── cli.ts                      # CLI entry point (SHELL)
+│   ├── analyzer.ts                 # Orchestration (SHELL)
+│   ├── extraction/
+│   │   ├── extractor.ts            # ts-morph project loading (SHELL)
+│   │   └── extract-functions.ts    # AST → ExtractedFunction (SHELL)
+│   ├── detection/
+│   │   ├── markers.ts              # Marker type definitions & catalog (PURE)
+│   │   └── detect-markers.ts       # ExtractedFunction → ImpurityMarker[] (PURE)
+│   ├── classification/
+│   │   ├── classifier.ts           # Markers → Classification (PURE)
+│   │   ├── quality-scorer.ts       # Impure function → Quality score (PURE)
+│   │   └── derive-status.ts        # Classification + Quality → Status (PURE)
+│   ├── scoring/
+│   │   └── scorer.ts               # Classifications → Scores (PURE)
+│   ├── reporting/
+│   │   ├── report-json.ts          # JSON output (SHELL)
+│   │   └── report-console.ts       # Console output (SHELL)
+│   └── types.ts                    # Shared type definitions (INFRASTRUCTURE)
+├── tests/
+│   ├── detect-markers.test.ts
+│   ├── classifier.test.ts
+│   ├── quality-scorer.test.ts
+│   ├── derive-status.test.ts
+│   ├── scorer.test.ts
+│   └── integration.test.ts
+├── plans/
+│   └── 001-fcis-analyzer.md
+├── vendor/
+│   └── ts-morph/                   # Reference only — use npm package
+├── package.json
+├── tsconfig.json
+├── README.md
+└── TECHNICAL.md
+```
+
+## Critical Type Declarations
+
+```typescript
+// types.ts
+
+// CallSite captures position and context for each call expression,
+// enabling future sequence analysis (GATHER→DECIDE→EXECUTE detection)
+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`?
+}
+
+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'
+}
+
+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 (see Addendum)
+type MarkerType =
+  | 'await-expression'
+  | 'database-call'
+  | 'network-fetch'
+  | 'network-http'
+  | 'fs-import'
+  | 'fs-call'
+  | 'env-access'
+  | 'console-log'
+  | 'logging'
+  | 'telemetry'
+  | 'queue-enqueue'
+  | 'event-emit'
+
+type ImpurityMarker = {
+  type: MarkerType
+  detail: string                      // e.g. "db.user.findFirst"
+}
+
+// Binary classification — objective, no heuristics
+type FunctionClassification = 'pure' | 'impure'
+
+// Derived status for UX — actionable guidance
+type Status = 'ok' | 'review' | 'refactor'
+
+type ClassifiedFunction = ExtractedFunction & {
+  markers: ImpurityMarker[]
+  classification: FunctionClassification
+  qualityScore: number | null         // 0-100 for impure functions; null for pure
+  status: Status                      // derived from classification + qualityScore
+}
+
+type StatusBreakdown = {
+  ok: number
+  review: number
+  refactor: number
+}
+
+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
+  refactoringCandidates: { 
+    name: string | null
+    startLine: number
+    bodyLineCount: number
+    qualityScore: number
+    markers: MarkerType[]
+  }[]
+  // Edge case flags
+  allExcluded?: boolean               // true if all functions were excluded
+  typeOnly?: boolean                  // true if file has only type/interface/enum exports
+}
+
+type DirectoryScore = {
+  dirPath: string
+  purity: number
+  impurityQuality: number | null
+  health: number
+  pureCount: number
+  impureCount: number
+  statusBreakdown: StatusBreakdown
+  pureLineCount: number
+  impureLineCount: number
+  fileScores: FileScore[]
+}
+
+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: { 
+    name: string | null
+    filePath: string
+    startLine: number
+    bodyLineCount: number
+    qualityScore: number
+    markers: MarkerType[]
+  }[]
+  // 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?: { filePath: string; error: string }[]
+}
+```
+
+## Tests
+
+### Unit Tests (Pure Core — No Mocks Needed)
+
+**`detect-markers.test.ts`** — For each marker category, provide an `ExtractedFunction` with known `callSites` / `propertyAccessChains` values and assert the correct markers are returned. High-risk areas:
+- Database call pattern matching (various `db.*.operation` forms)
+- `async` alone (without await or other I/O) produces NO markers
+- Network fetch detection
+- File system import detection
+
+**`classifier.test.ts`** — Provide function data with marker combinations and assert classification:
+- Zero markers → **pure**
+- Only `async` keyword (no `await`, no other markers) → **pure**
+- Has `await-expression` marker → **impure**
+- Has `database-call` marker → **impure**
+- Has any I/O marker → **impure**
+- Trivial function (< 3 statements, no conditionals) → excluded
+
+**`quality-scorer.test.ts`** — Provide impure function data and assert quality scores:
+- Impure function calling `.pure.ts` import → high score (≥70)
+- Impure function calling `planAcceptInvite` → high score (≥70)  
+- Impure function with I/O at start and end only → medium-high score
+- Impure function with I/O interleaved throughout → low score (<40)
+- Impure function with high cyclomatic complexity → score penalty applied
+- Impure function with no pure function calls → score penalty applied
+
+**`derive-status.test.ts`** — Verify status derivation:
+- Pure function → status `ok`
+- Impure with qualityScore ≥ 70 → status `ok`
+- Impure with qualityScore 40-69 → status `review`
+- Impure with qualityScore < 40 → status `refactor`
+
+**`scorer.test.ts`** — Provide classification arrays with quality scores and assert metrics:
+- All pure → purity: 100, health: 100
+- All impure with high quality (≥70) → purity: 0, impurityQuality: high, health: 100
+- All impure with low quality (<40) → purity: 0, impurityQuality: low, health: 0
+- 50/50 pure/impure with mixed quality → verify purity, impurityQuality, health calculations
+- Empty file → health: 100 (no functions to score)
+- All excluded → health: 100 with `allExcluded: true`
+- Verify `refactoringCandidates` is sorted by `bodyLineCount × (100 - qualityScore)` descending
+
+### Integration Test
+
+**`integration.test.ts`** — Use ts-morph's in-memory file system to create a small multi-file project with known patterns, run the full pipeline (extract → detect → classify → score), and assert the end-to-end result. This test validates that the extraction layer and pure core agree on real TypeScript ASTs.
+
+**Snapshot Testing:**
+- Snapshot the full JSON output for known fixtures using Vitest's `toMatchSnapshot()`
+- Snapshots serve as documentation of expected output format
+- Review snapshot changes carefully during PR review
+
+Test fixture should include:
+- A pure function (no I/O markers)
+- An async function without await (should classify as pure)
+- An impure function with high quality score (calls `.pure.ts` import, I/O at edges)
+- An impure function with low quality score (interleaved `db.*` calls, high complexity)
+- A type-only file (should be excluded)
+- A file with only trivial functions (should be excluded)
+
+## Transitive Effect Analysis
+
+This tool is a new standalone package. It has **no transitive effects** on the SchoolAI codebase — it reads source files but does not modify them. The only integration point is if added to CI, where a `--min-score` failure could block a PR.
+
+Within the tool itself:
+- Changes to `markers.ts` (marker catalog) affect `detect-markers.ts` outputs, which cascade to `classifier.ts` and `scorer.ts`. All three are covered by unit tests.
+- Changes to `types.ts` affect every module. Keep types minimal and stable.
+- Changes to `extractor.ts` or `extract-functions.ts` (AST extraction) affect all downstream modules but are isolated behind the `ExtractedFunction` interface boundary — downstream modules never see ts-morph types.
+- ts-morph version updates could change AST behavior. Pin the version and test against known fixtures.
+
+## Extensibility (Post-v1)
+
+The marker catalog is defined as a data structure in `markers.ts`, enabling future extensibility:
+
+- Custom markers can be added by extending the `MarkerType` union and catalog
+- Post-v1: Support a `fcis.config.ts` file for project-specific marker definitions:
+  ```typescript
+  // fcis.config.ts
+  export default {
+    customMarkers: [
+      { pattern: '@sai/analytics.*', type: 'custom-analytics', severity: 'medium' },
+      { pattern: 'trackEvent', type: 'custom-analytics', severity: 'medium' },
+    ]
+  }
+  ```
+- Custom markers appear in output alongside built-in markers
+- This enables SchoolAI-specific patterns without forking the core tool
+
+## Resources for Implementation Context
+
+These files should be included in context when implementing each phase:
+
+**Phase 2 (Extraction):**
+- `fcis/vendor/ts-morph/packages/ts-morph/src/compiler/ast/base/AsyncableNode.ts` — `isAsync()` API
+- `fcis/vendor/ts-morph/packages/ts-morph/src/compiler/ast/expression/AwaitExpression.ts` — await detection
+- `fcis/vendor/ts-morph/packages/ts-morph/src/compiler/ast/expression/CallExpression.ts` — call expression API
+- `fcis/vendor/ts-morph/packages/ts-morph/src/compiler/ast/common/Node.ts` — `getDescendantsOfKind`, `forEachDescendant`
+- `fcis/vendor/ts-morph/packages/ts-morph/src/compiler/ast/function/FunctionDeclaration.ts` — function declaration API
+- `fcis/vendor/ts-morph/docs/navigation/example.md` — ts-morph navigation patterns
+- `fcis/vendor/ts-morph/docs/setup/index.md` — project setup
+
+**Phase 3 (Detection) — Target Codebase Patterns:**
+- `apps/web/src/server/services/organizations.pure.ts` — gold standard pure function
+- `apps/web/src/server/services/organizations.ts` L97-186 — shell pattern (acceptInvite with GATHER→DECIDE→EXECUTE)
+- `apps/web/src/server/services/moderation.ts` — mixed file with embedded pure functions (`shouldModerate`, `shouldSendRedAlertEmail`, `getRedAlertType`)
+- `apps/web/src/server/services/students.ts` — typical mixed service code
+- `apps/web/src/server/services/chat.ts` — heavily mixed service code
+- `ai-platform/apps/server/src/v1/blueprints/nodes/llm-v2/prepare-provider-request.ts` — large pure function
+
+**Phase 4 (Classification) — Target Codebase Patterns:**
+- `apps/web/src/components/Carousel/CarouselCommon.ts` — extracted pure utility
+- `apps/web/src/components/MissionControl/Participants/Header/sortByUtil.ts` — pure sort functions
+
+**Phase 8 (Baseline) — Validation Targets:**
+- `apps/web/src/server/services/organizations.pure.test.ts` — demonstrates pure function testing
+- `ai-platform/apps/server/src/v1/blueprints/nodes/llm-v2/prepare-provider-request.unit.test.ts` — pure function tests with no mocks
+- `apps/web/src/server/services/moderation.test.ts` — mixed testing requiring mocks
+- `ai-platform/apps/server/src/v1/services/projects/projects.ts` — `buildProjectService` pattern with `toPublicProject` pure transformer
+- `packages/utils/src/fuzzy-enum.ts` — naturally pure utility
+- `packages/utils/src/string-template.ts` — naturally pure utility
+
+## Documentation
+
+### README.md
+
+Create with: overview, installation, CLI usage examples, score interpretation guide, and a worked example of refactoring a mixed function into pure + shell.
+
+### TECHNICAL.md
+
+Create with: architecture diagram, type definitions reference, marker catalog, classification rules, scoring formula, and extension guide (how to add new markers).
+
+---
+
+## Addendum: Frontend Component Analysis (v2)
+
+**Status:** Deferred to v2. This section documents the planned approach for analyzing `.tsx` files and React components.
+
+### Rationale for Deferral
+
+React components require different metrics than backend functions:
+- The core FCIS question for backend code is: *"Can this function's logic be tested without mocking?"*
+- The equivalent question for frontend components is: *"Can this component's visual states be demonstrated in Storybook without mocking the data layer?"*
+
+These are related but distinct problems. v1 focuses on the backend question for `.ts` files. v2 will extend to React components.
+
+### Planned Approach for v2
+
+#### React Hook Markers
+
+Add markers for React hooks (impurity in component context):
+- `use[A-Z]*` pattern → marker `react-hook`
+- `useState`, `useEffect`, `useLayoutEffect`, `useReducer`, `useRef`, `useContext`, `useCallback` → `react-state-hook` or `react-effect-hook`
+- `useQuery`, `useMutation`, `useSWR` → `react-data-hook`
+- `useRouter`, `useNavigate`, `useSearchParams` → `react-navigation-hook`
+
+#### JSX Complexity Detection
+
+For `.tsx` files with JSX, extract additional markers:
+- Conditional expressions in JSX (`{x ? a : b}`) → marker `jsx-ternary`
+- Logical AND rendering (`{x && <Foo />}`) → marker `jsx-logical-and`
+- Nested ternaries → marker `jsx-nested-ternary` (high severity)
+- Inline callbacks with > 1 statement → marker `jsx-complex-callback`
+
+Compute `jsxComplexity` score based on these markers.
+
+#### Component Classification
+
+For React components, apply a separate classification:
+
+| Classification | Criteria | Storybook-able? |
+|---------------|----------|-----------------|
+| **Presentational** | No hooks, all state via props | Yes |
+| **Container** | Has hooks, low jsxComplexity, delegates rendering | Partial — children are |
+| **Entangled** | Has hooks AND high jsxComplexity | No |
+| **Page/Layout** | Route-level orchestration | N/A — infrastructure |
+
+#### Effect Concentration Metric
+
+Measure where hooks are used in the component tree:
+- Healthy: Most hooks in pages/containers (top of tree)
+- Problematic: Hooks scattered throughout leaf components
+
+`effectConcentrationScore = (effectsInPages + effectsInContainers) / totalHookCalls`
+
+#### Frontend-Specific Types (v2)
+
+```typescript
+type JSXMarker = {
+  type: 'jsx-ternary' | 'jsx-logical-and' | 'jsx-nested-ternary' | 'jsx-complex-callback'
+  detail: string
+  line: number
+}
+
+type ComponentClassification = 'presentational' | 'container' | 'entangled' | 'page'
+
+type ClassifiedComponent = ClassifiedFunction & {
+  jsxComplexity: number
+  jsxMarkers: JSXMarker[]
+  componentClassification: ComponentClassification
+}
+
+type FrontendScore = {
+  presentationalCount: number
+  containerCount: number
+  entangledCount: number
+  pageCount: number
+  effectsInPages: number
+  effectsInContainers: number
+  effectsInLeaves: number
+  effectConcentrationScore: number        // 0-100, higher is better
+  representabilityScore: number           // (presentational + container) / (total - pages)
+  topEntangledComponents: { 
+    name: string | null
+    filePath: string
+    startLine: number
+    jsxComplexity: number
+    hookCount: number
+  }[]
+}
+```
+
+#### v2 CLI Extensions
+
+```
+--include-tsx              Include .tsx files in analysis (v2)
+--min-frontend-score <N>   Exit with code 1 if frontend representability score < N
+```
+
+#### v2 Target Files for Validation
+
+- `apps/web/src/hooks/useSettingsRoutes.ts` — FCIS in React (pure derivations + hook shell)
+- `apps/web/src/hooks/useSpaceLaunchStatus.ts` — hook with `useMemo` wrapping pure logic
+- `apps/web/src/components/Carousel/Cards/SpaceCard.tsx` — mixed component with inline logic
+- `apps/web/src/components/` — scan for JSX complexity patterns
+- `apps/web/src/app/` — Next.js app router pages for page classification baseline