fcis 0.1.0 → 0.2.0

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: