fcis 0.1.0 → 0.2.0

package/.plans/007-compositional-function-scoring.md

@@ -0,0 +1,514 @@
+# Plan 007: Compositional Function Scoring
+
+## Background
+
+The FCIS analyzer currently treats every function independently, including inline arrow functions passed as callbacks to methods like `.map()`, `.filter()`, `.forEach()`, and `.reduce()`. This creates several problems:
+
+1. **Inflated function counts:** A single 301-line function with 6 inline callbacks is counted as 7 functions
+2. **Diluted health scores:** Non-trivial callbacks (≥3 statements or with conditionals) that score "ok" can mask a severely problematic parent function. Note: trivial callbacks (< 3 statements, no conditionals) are already excluded by `shouldExcludeFunction()`, so the dilution effect applies specifically to substantive callbacks — still common in `.map()` calls that build objects, `.forEach()` with conditional logic, etc.
+3. **Double-counting impurity:** If a callback is impure (e.g., calls `log()`), that impurity should bubble up to the parent
+4. **Double-counting line counts:** Parent `bodyLineCount` already includes nested callback lines, but callbacks are also counted separately — summing all functions' line counts overcounts actual code
+5. **Misrepresentation:** High function counts suggest good decomposition when the reality is a monolith with inline callbacks
+6. **Pre-existing bug — `checkForConditionals` leaks across boundaries:** Unlike `extractCallSites()`, `checkForAwait()`, and `extractPropertyAccessChains()` which all use `traversal.skip()` at nested function boundaries, `checkForConditionals()` descends into nested functions. This means a ternary inside a callback inflates the parent's `hasConditionals` flag, affecting both trivial-function exclusion and complexity estimation in the quality scorer.
+
+### Example: `missionControlData.ts`
+
+Current scoring:
+- 7 functions counted (1 main + 6 callbacks)
+- 71% health (5 ok, 1 review, 1 refactor)
+- 57% purity
+
+Reality:
+- 1 main function (301 lines, severely tangled)
+- 3 pure helper functions
+- Health should be ~50% to reflect the severity of the main function
+
+## Problem Statement
+
+The current function-by-function scoring model doesn't account for compositional relationships between functions. Inline callbacks should be absorbed into their parent function's score rather than counted independently.
+
+## Success Criteria
+
+1. `checkForConditionals` correctly scopes to the immediate function body (no leaking)
+2. Inline callbacks are marked with their parent function reference during extraction
+3. Scoring absorbs inline callbacks into their parent function
+4. Impurity in callbacks bubbles up to the parent function
+5. Child quality scores influence parent quality through weighted composition
+6. Function counts reflect "top-level" functions, not inline callbacks
+7. Line counts no longer double-count nested callback lines
+8. Detailed callback data remains available for drill-down analysis
+9. All existing tests continue to pass (with updated expectations where appropriate)
+
+## The Gap
+
+| Aspect | Current State | Target State |
+|--------|---------------|--------------|
+| `checkForConditionals` | Leaks into nested functions | Scoped to immediate body |
+| Inline callbacks | Scored independently | Absorbed into parent |
+| Function counts | Includes all callbacks | Only top-level functions |
+| Line counts | Double-counted for nested functions | No double-counting |
+| Impurity inheritance | None | Bubbles up from children |
+| Quality composition | None | Children influence parent |
+| Data availability | Flat list | Hierarchical with parent refs |
+
+## Design
+
+### Type Changes
+
+```typescript
+// In types.ts - ExtractedFunction
+export type ExtractedFunction = {
+  // ... existing fields ...
+
+  // NEW: Reference to parent function (for inline callbacks)
+  // null when: (a) not an inline callback, or (b) callback is at module scope (no enclosing function)
+  enclosingFunctionStartLine: number | null
+
+  // NEW: Flag indicating this is an inline callback to a known HOF
+  isInlineCallback: boolean
+}
+
+// In types.ts - ClassifiedFunction (inherits from ExtractedFunction)
+// No additional changes needed - inherits new fields
+```
+
+### Higher-Order Function Detection
+
+Callbacks passed to these methods are considered inline callbacks:
+- Array methods: `map`, `filter`, `reduce`, `forEach`, `find`, `findIndex`, `some`, `every`, `flatMap`, `sort`, `toSorted`
+- Promise methods: `then`, `catch`, `finally`
+- Other common HOFs: `setTimeout`, `setInterval`, `addEventListener`, `on`, `once`
+
+**Explicit exclusion — NOT inline callbacks:**
+- tRPC handlers (`query`, `mutation`, `subscription`) — these are conceptually separate endpoints
+- Express/framework middleware (`use`, `get`, `post`, `put`, `delete`, `patch`)
+- Custom application HOFs (e.g., `withAuth`, `createHandler`)
+
+These are intentionally excluded because they represent distinct units of behavior, not helper logic absorbed into a parent. They should continue to be scored independently.
+
+### Enclosing Function Discovery
+
+Finding the enclosing function for a callback requires an **AST upward walk** from the callback node:
+
+```typescript
+function findEnclosingFunctionStartLine(node: Node): number | null {
+  let current = node.getParent()
+  while (current) {
+    const kind = current.getKind()
+    if (
+      kind === SyntaxKind.FunctionDeclaration ||
+      kind === SyntaxKind.MethodDeclaration ||
+      kind === SyntaxKind.ArrowFunction ||
+      kind === SyntaxKind.FunctionExpression ||
+      kind === SyntaxKind.GetAccessor ||
+      kind === SyntaxKind.SetAccessor
+    ) {
+      return current.getStartLineNumber()
+    }
+    current = current.getParent()
+  }
+  return null // module-scope callback, no enclosing function
+}
+```
+
+When `enclosingFunctionStartLine` is `null`, the callback is at module scope and should be treated independently (not absorbed into any parent).
+
+### Naming for Inline Callbacks
+
+Currently, `parentContext` is overloaded — it serves as both the function's `name` (when no intrinsic name exists) and the calling context. For inline callbacks, this means a callback to `.forEach()` gets `name = "forEach"`.
+
+After adding `isInlineCallback`, we preserve this behavior. The `name` field continues to use `parentContext` as before — the `isInlineCallback` flag provides the semantic disambiguation. Consumers can check `isInlineCallback` to know that `name = "forEach"` means "anonymous callback passed to forEach" rather than "a function named forEach."
+
+### Impurity Bubbling Rules
+
+1. If a callback is impure, the parent function is also impure
+2. Exception: Pure higher-order functions that don't execute their callback immediately (e.g., returning a function) — deferred to future iteration
+3. For v1, we use a simple rule: **any impure child makes the parent impure**
+
+**Positive finding from research:** `extractCallSites()`, `checkForAwait()`, and `extractPropertyAccessChains()` already use `traversal.skip()` to stop at nested function boundaries. Markers are correctly attributed only to the function that directly contains the call. This means Phase 3 can simply look at classified children's markers and propagate them upward — no changes to the detection layer are needed.
+
+### Quality Composition Formula
+
+**Revised:** The original multiplicative formula (`parentQuality × childFactor`) was too punitive — a parent with quality 60 and a single impure child with quality 40 would drop to 24, turning a "review" into "refactor" disproportionately.
+
+Instead, we use a **line-count-weighted blend** of parent and children qualities:
+
+```
+composedQuality = (parentBaseQuality × parentOwnLineCount + Σ(childQuality × childLineCount)) / totalLineCount
+
+where:
+  parentOwnLineCount = parent.bodyLineCount - Σ(child.bodyLineCount)
+  totalLineCount = parentOwnLineCount + Σ(child.bodyLineCount)
+```
+
+This means:
+- A 50-line parent (quality 60) with a 10-line impure child (quality 40): `(60×40 + 40×10) / 50 = 56` → stays "review"
+- A 50-line parent (quality 60) with a 40-line impure child (quality 20): `(60×10 + 20×40) / 50 = 28` → correctly drops to "refactor" because the child dominates
+- All children pure: composed quality = parent quality (children don't contribute impure quality)
+
+Note: `parentOwnLineCount` is clamped to `max(1, ...)` to avoid division by zero.
+
+When **all children are pure**, only the parent's impure quality matters — pure children don't factor into the impurity quality calculation. The formula only blends when there are impure children.
+
+## Phases and Tasks
+
+### Phase 0: Fix `checkForConditionals` Scoping Bug ✅
+
+- Add `traversal.skip()` for nested function nodes in `checkForConditionals()` ✅
+- Add test verifying conditionals in nested callbacks don't leak to parent ✅
+- Add test verifying conditionals in the parent itself are still detected ✅
+
+This is a pre-existing bug that should be fixed before building compositional scoring on top of the extraction data. It's a ~5-line fix.
+
+**Files to modify:**
+- `fcis/src/extraction/extract-functions.ts`
+
+**Files to add/update tests:**
+- `fcis/tests/integration.test.ts` (or a new focused extraction test)
+
+### Phase 1: Update Extraction to Mark Inline Callbacks ✅
+
+- Add `enclosingFunctionStartLine` and `isInlineCallback` fields to `ExtractedFunction` type ✅
+- Update `extractFunctionData()` to accept and set these fields ✅
+- Implement `findEnclosingFunctionStartLine()` AST upward-walk helper ✅
+- Update `extractFunctions()` to detect inline callbacks in the `forEachDescendant` sweep:
+  - Check if the arrow/function-expression's parent is a `CallExpression` with a known HOF name (via `inferParentContext`) ✅
+  - If so, set `isInlineCallback = true` and walk up the AST to find `enclosingFunctionStartLine` ✅
+  - If the callback is at module scope (no enclosing function), `enclosingFunctionStartLine = null` — treat independently ✅
+- Add tests for inline callback detection ✅
+
+Known HOF names to detect:
+```typescript
+const INLINE_CALLBACK_METHODS = new Set([
+  // Array methods
+  'map', 'filter', 'reduce', 'forEach', 'find', 'findIndex',
+  'some', 'every', 'flatMap', 'sort', 'toSorted',
+  // Promise methods
+  'then', 'catch', 'finally',
+  // Timing
+  'setTimeout', 'setInterval',
+  // Events
+  'addEventListener', 'on', 'once',
+])
+```
+
+### Phase 2: Update Scoring to Absorb Callbacks ✅
+
+- Create `groupFunctionsByParent()` helper to build parent-child relationships using `enclosingFunctionStartLine` ✅
+- Create `computeCompositionalScore()` to calculate scores with child absorption ✅
+- Update `scoreFile()` to use compositional scoring ✅
+- Ensure function counts only include top-level functions (where `isInlineCallback === false` or `enclosingFunctionStartLine === null`) ✅
+- Fix line count double-counting: only sum top-level function line counts (parent `bodyLineCount` already includes nested callback lines) ✅
+- Add tests for compositional scoring ✅
+
+### Phase 3: Update Classification for Impurity Bubbling ✅
+
+- Update classification logic to check children's impurity ✅ (done in scorer via `isEffectivelyImpure()`)
+- If any child is impure, parent is impure ✅ (done in scorer via `isEffectivelyImpure()`)
+- Aggregate markers from children into parent (detection layer already scopes markers correctly — no detection changes needed) ✅ (done in refactoring candidates)
+- Add tests for impurity bubbling ✅
+
+### Phase 4: Update Quality Scoring for Composition ✅
+
+- Implement line-count-weighted blend formula for composed quality ✅
+- Calculate `parentOwnLineCount` as `parent.bodyLineCount - Σ(child.bodyLineCount)`, clamped to `max(1, ...)` ✅
+- Only blend impure children into the quality calculation (pure children don't affect impurity quality) ✅
+- Add tests for quality composition ✅
+
+### Phase 5: Update Reporting ✅
+
+- Update console report to show composed function counts ✅ (automatic via scorer changes)
+- Keep inline callbacks in JSON output for drill-down (with `isInlineCallback: true`) ✅ (functions array preserved)
+- Update refactoring candidates to use composed scores ✅ (done in Phase 2/3)
+- Add tests for reporting changes ✅ (verified via CLI output)
+
+### Phase 6: Documentation ✅
+
+- Update TECHNICAL.md with compositional scoring explanation ✅
+- Update README.md if user-facing behavior changes ✅
+
+## Tests
+
+### Phase 0: Scoping Bug Fix Tests
+
+```typescript
+describe('checkForConditionals scoping', () => {
+  it('should NOT detect conditionals inside nested callbacks', () => {
+    const code = `
+      function outer() {
+        const x = items.map(item => item.active ? item.name : 'unknown')
+        return x
+      }
+    `
+    const functions = extractFunctions(createSourceFile(code))
+    const outer = functions.find(f => f.name === 'outer')
+    expect(outer?.hasConditionals).toBe(false)
+  })
+
+  it('should still detect conditionals in the function itself', () => {
+    const code = `
+      function outer() {
+        if (items.length === 0) return []
+        return items
+      }
+    `
+    const functions = extractFunctions(createSourceFile(code))
+    const outer = functions.find(f => f.name === 'outer')
+    expect(outer?.hasConditionals).toBe(true)
+  })
+})
+```
+
+### Phase 1: Extraction Tests
+
+```typescript
+describe('inline callback detection', () => {
+  it('should mark arrow functions passed to map as inline callbacks', () => {
+    const code = `
+      const result = items.map(item => item.value)
+    `
+    const functions = extractFunctions(createSourceFile(code))
+    const callback = functions.find(f => f.parentContext === 'map')
+    expect(callback?.isInlineCallback).toBe(true)
+    expect(callback?.enclosingFunctionStartLine).toBeNull() // module-scope
+  })
+
+  it('should link nested callbacks to their enclosing function', () => {
+    const code = `
+      function outer() {
+        items.forEach(item => {
+          console.log(item)
+        })
+      }
+    `
+    const functions = extractFunctions(createSourceFile(code))
+    const outer = functions.find(f => f.name === 'outer')
+    const callback = functions.find(f => f.parentContext === 'forEach')
+    expect(callback?.isInlineCallback).toBe(true)
+    expect(callback?.enclosingFunctionStartLine).toBe(outer?.startLine)
+  })
+
+  it('should NOT mark callbacks to unknown methods as inline', () => {
+    const code = `
+      const result = customMethod(item => item.value)
+    `
+    const functions = extractFunctions(createSourceFile(code))
+    const callback = functions.find(f => f.parentContext === 'customMethod')
+    expect(callback?.isInlineCallback).toBe(false)
+  })
+
+  it('should NOT mark tRPC handlers as inline callbacks', () => {
+    const code = `
+      export const router = createRouter({
+        getUser: query(async ({ ctx }) => {
+          return await ctx.db.user.findFirst()
+        }),
+      })
+    `
+    const functions = extractFunctions(createSourceFile(code))
+    const handler = functions.find(f => f.parentContext === 'query')
+    expect(handler?.isInlineCallback).toBe(false)
+  })
+
+  it('should handle deeply nested callbacks with correct enclosing function', () => {
+    const code = `
+      function process() {
+        items.forEach(item => {
+          item.tags.map(tag => tag.name)
+        })
+      }
+    `
+    const functions = extractFunctions(createSourceFile(code))
+    const process = functions.find(f => f.name === 'process')
+    const forEachCb = functions.find(f => f.parentContext === 'forEach')
+    const mapCb = functions.find(f => f.parentContext === 'map')
+    // Both callbacks link to the enclosing named function
+    expect(forEachCb?.enclosingFunctionStartLine).toBe(process?.startLine)
+    // The map callback's enclosing function is the forEach callback
+    expect(mapCb?.enclosingFunctionStartLine).toBe(forEachCb?.startLine)
+  })
+})
+```
+
+### Phase 2: Scoring Tests
+
+```typescript
+describe('compositional scoring', () => {
+  it('should count only top-level functions', () => {
+    // File with 1 function containing 3 inline callbacks
+    const score = scoreFile(path, classifiedFunctions)
+    expect(score.pureCount + score.impureCount).toBe(1) // not 4
+  })
+
+  it('should not double-count line counts', () => {
+    // Parent: 50 lines (includes callback), Callback: 10 lines
+    // pureLineCount + impureLineCount should equal 50, not 60
+  })
+
+  it('should treat module-scope inline callbacks independently', () => {
+    // Top-level: items.map(item => { ... complex ... })
+    // No enclosing function — should count as its own function
+  })
+})
+```
+
+### Phase 3: Impurity Bubbling Tests
+
+```typescript
+describe('impurity bubbling', () => {
+  it('should make parent impure if callback is impure', () => {
+    // Parent function with pure code
+    // Callback that calls console.log
+    // Parent should be classified as impure
+  })
+
+  it('should aggregate markers from children', () => {
+    // Parent with database-call
+    // Callback with logging
+    // Parent should have both markers
+  })
+
+  it('should not affect parent if callback is pure', () => {
+    // Parent with database-call
+    // Callback that is pure (e.g., items.map(x => x.name))
+    // Parent markers unchanged
+  })
+})
+```
+
+### Phase 4: Quality Composition Tests
+
+```typescript
+describe('quality composition', () => {
+  it('should blend parent and impure child quality by line count', () => {
+    // Parent: 50 total lines, 40 own lines, quality 60
+    // Child: 10 lines, quality 40
+    // Composed: (60*40 + 40*10) / 50 = 56
+  })
+
+  it('should not affect quality if all children are pure', () => {
+    // Parent base quality: 60
+    // All children pure
+    // Composed: 60 (unchanged)
+  })
+
+  it('should weight heavily toward child when child dominates line count', () => {
+    // Parent: 50 total lines, 10 own lines, quality 60
+    // Child: 40 lines, quality 20
+    // Composed: (60*10 + 20*40) / 50 = 28
+  })
+})
+```
+
+## Transitive Effect Analysis
+
+### Phase 0 (Bug Fix)
+- `extract-functions.ts` → `checkForConditionals()` adds `traversal.skip()` for nested functions
+- May change `hasConditionals` values for functions that contain callbacks with conditionals
+- Could affect `shouldExcludeFunction()` decisions (some parent functions may now be correctly excluded as trivial)
+- Could affect quality scorer's complexity estimation (more accurate now)
+
+### Phase 1 (Extraction)
+- `types.ts` → adds new fields to `ExtractedFunction`
+- `extract-functions.ts` → uses new fields, adds AST upward-walk helper
+- All consumers of `ExtractedFunction` will see new fields (backward compatible, fields have defaults)
+
+### Phase 2 (Scoring)
+- `scorer.ts` → new grouping and composition logic
+- `scoreFile()` return values change (function counts may decrease, line counts decrease)
+- Tests that assert specific function counts will need updates
+
+### Phase 3 (Classification)
+- `classifier.ts` → needs access to child functions for impurity bubbling
+- `analyzer.ts` → may need to pass additional context to classification
+- Detection layer (`detect-markers.ts`) does NOT need changes — markers are already correctly scoped
+
+### Phase 4 (Quality)
+- `quality-scorer.ts` → new composition logic using weighted blend
+- Quality scores may change for functions with impure children
+
+### Phase 5 (Reporting)
+- `report-console.ts` → function counts reflect composed scores
+- `report-json.ts` → includes `isInlineCallback` field for filtering
+- Downstream JSON consumers may see different counts
+
+## Resources for Implementation
+
+**Files to modify:**
+- `fcis/src/extraction/extract-functions.ts` — Phase 0, Phase 1
+- `fcis/src/types.ts` — Phase 1
+- `fcis/src/scoring/scorer.ts` — Phase 2
+- `fcis/src/classification/classifier.ts` — Phase 3
+- `fcis/src/classification/quality-scorer.ts` — Phase 4
+- `fcis/src/reporting/report-console.ts` — Phase 5
+- `fcis/src/reporting/report-json.ts` — Phase 5
+- `fcis/src/analyzer.ts` — Phase 2, 3 (orchestration changes)
+
+**Files to add/update tests:**
+- `fcis/tests/integration.test.ts` — Phase 0, Phase 1
+- `fcis/tests/scorer.test.ts` — Phase 2
+- `fcis/tests/classifier.test.ts` — Phase 3
+- `fcis/tests/quality-scorer.test.ts` — Phase 4
+
+**Reference files:**
+- `apps/web/src/server/services/spaces/missionControlData.ts` — real-world test case
+- `apps/web/src/server/utils/history/filterSystemMessages.ts` — pure functions baseline
+
+## Documentation Updates
+
+### TECHNICAL.md
+
+Add section:
+
+```markdown
+## Compositional Function Scoring
+
+FCIS uses compositional scoring to handle inline callbacks (arrow functions passed to `map`, `filter`, `forEach`, etc.):
+
+### Inline Callback Detection
+
+Functions are marked as inline callbacks when passed to known higher-order functions:
+- Array methods: `map`, `filter`, `reduce`, `forEach`, `find`, `some`, `every`, etc.
+- Promise methods: `then`, `catch`, `finally`
+- Timing/events: `setTimeout`, `addEventListener`, etc.
+
+Framework-specific handlers (tRPC `query`/`mutation`, Express middleware, etc.) are intentionally NOT treated as inline callbacks — they represent distinct behavioral units.
+
+### Enclosing Function Discovery
+
+Each inline callback is linked to its enclosing function via an AST upward walk. Callbacks at module scope (no enclosing function) are treated independently.
+
+### Impurity Bubbling
+
+If an inline callback is impure, the enclosing function is also considered impure. Markers from children are aggregated into the parent. The detection layer already scopes markers to the immediate function, so bubbling is a classification-time concern.
+
+### 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)`. Pure children do not factor into the impurity quality calculation.
+
+### Function Counts
+
+Only top-level functions are counted in health/purity metrics. Inline callbacks are absorbed into their parent's score but remain available in JSON output with `isInlineCallback: true` for detailed analysis. Line counts no longer double-count nested callback lines.
+```
+
+## Estimated Line Impact
+
+- Phase 0 (Bug Fix): ~15 lines changed/added (including tests)
+- Phase 1 (Extraction): ~100 lines changed/added (includes AST upward-walk helper)
+- Phase 2 (Scoring): ~100 lines changed/added
+- Phase 3 (Classification): ~50 lines changed/added
+- Phase 4 (Quality): ~40 lines changed/added
+- Phase 5 (Reporting): ~30 lines changed/added
+- Phase 6 (Documentation): ~40 lines
+- Tests: ~250 lines added
+
+**Total: ~625 lines** — within the 2000 line PR limit, but consider splitting into 2-3 PRs:
+- PR 1: Phase 0 (bug fix — tiny, can merge independently)
+- PR 2: Phases 1-2 (extraction + scoring foundation)
+- PR 3: Phases 3-6 (classification, quality, reporting, docs)

package/README.md

@@ -33,7 +33,7 @@ npx fcis tsconfig.json --files "src/services/**/*.ts"
 
 ### Purity (0-100%)
 
-Percentage of functions that are **pure** — no I/O markers detected. Pure functions:
+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
@@ -47,7 +47,18 @@ For impure functions, measures how **well-structured** the I/O code is:
 
 ### Health (0-100%)
 
-Percentage of functions with status **OK** (either pure, or impure with quality ≥70).
+Percentage of top-level functions with status **OK** (either pure, or impure with quality ≥70).
+
+### Compositional Scoring
+
+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
+
+If a callback is impure, the parent is considered effectively impure. Quality scores are blended by line count.
+
+See [TECHNICAL.md](./TECHNICAL.md#compositional-function-scoring) for details.
 
 ## Function Classification
 
@@ -78,7 +89,6 @@ The analyzer detects these I/O patterns:
 | `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 |
@@ -104,6 +114,7 @@ Options:
   --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
@@ -146,6 +157,30 @@ Top Refactoring Candidates:
       Markers: database-call, await-expression
 ```
 
+### Directory Rollup
+
+To see aggregate metrics for top-level directories instead of leaf directories:
+
+```bash
+fcis tsconfig.json --dir-depth 1
+```
+
+Example output:
+
+```
+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
+```
+
+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`.
+
 ## CI Integration
 
 ### GitHub Actions