fcis 0.1.0 → 0.2.1

package/.plans/003-code-cleanup-consolidation.md

@@ -0,0 +1,242 @@
+# Plan 003: FCIS Code Cleanup and Consolidation
+
+## Background
+
+After implementing Plan 002 (analyzer improvements), a code review identified several areas of technical debt:
+
+1. **Duplicated code**: tsconfig JSONC validation logic exists in both `cli.ts` and `extractor.ts`
+2. **Dead code**: `markers.ts` exports many utility functions that are never used
+3. **Orphaned types**: The `fs-import` marker type is defined but never detected after Phase 1 changes
+4. **Large function**: The CLI `main()` function handles too many responsibilities (~150 lines)
+5. **Missing validation**: The `--files` glob pattern is not validated
+
+The codebase follows FCIS patterns well architecturally, but accumulated cruft during iterative development.
+
+## Problem Statement
+
+Technical debt in the FCIS analyzer creates:
+- **Maintenance burden**: Duplicated validation logic must be kept in sync manually
+- **Confusion**: Dead code and orphaned types mislead future developers
+- **Test gaps**: The monolithic CLI function is difficult to unit test
+- **Poor UX**: Invalid glob patterns cause confusing runtime behavior
+
+## Success Criteria
+
+1. Single source of truth for tsconfig JSONC validation
+2. Zero dead/unused exports in `markers.ts`
+3. `MarkerType` union only contains actively detected markers
+4. CLI logic decomposed into testable pure functions
+5. Invalid `--files` glob patterns rejected with clear error message
+6. All existing tests continue to pass
+7. No new functionality—purely cleanup and consolidation
+
+## The Gap
+
+| Issue | Current State | Target State |
+|-------|---------------|--------------|
+| tsconfig validation | Duplicated in cli.ts and extractor.ts | Single exported function in extractor.ts |
+| markers.ts exports | 15+ unused functions/constants | Only used exports remain |
+| `fs-import` marker | In MarkerType but never detected | Removed from types and catalog |
+| CLI main() | ~150 line god function | Decomposed into 4-5 focused functions |
+| --files validation | Accepts any string | Validates glob syntax |
+
+## Phases and Tasks
+
+### Phase 1: Extract Shared tsconfig Validation ✅
+
+- Create `validateTsconfigContent()` function in `extractor.ts` ✅
+- Export the function for use by CLI ✅
+- Update `cli.ts` to import and use the shared function ✅
+- Update `loadProject()` to use the shared function internally ✅
+- Add unit test for `validateTsconfigContent()` ✅
+
+Function signature:
+```typescript
+export function validateTsconfigContent(
+  content: string
+): { valid: true } | { valid: false; error: string }
+```
+
+### Phase 2: Remove Dead Code from markers.ts ✅
+
+- Audit all exports in `markers.ts` against actual usage ✅
+- Remove unused functions: `isDatabaseCall`, `isFetchCall`, `isHttpClientCall`, `isFsCall`, `isFsModule`, `isEnvAccess`, `isConsoleCall`, `isLoggingCall`, `isTelemetryCall`, `isQueueEnqueueCall`, `isEventEmitCall` ✅
+- Remove unused functions: `getMarkersByCategory`, `getMarkersBySeverity` ✅
+- Remove unused constants: `DATABASE_PREFIXES`, `FS_MODULES`, `HTTP_MODULES`, `CONSOLE_METHODS`, `TELEMETRY_PATTERNS` ✅
+- Verify no imports break after removal ✅
+- Update `index.ts` exports if any removed items were re-exported ✅
+
+### Phase 3: Remove Orphaned fs-import Marker Type ✅
+
+- Remove `'fs-import'` from `MarkerType` union in `types.ts` ✅
+- Remove `'fs-import'` entry from `MARKER_CATALOG` in `markers.ts` ✅
+- Update TECHNICAL.md marker detection table to remove fs-import row 🔴 (Phase 6)
+- Verify no code references the removed marker type ✅
+
+### Phase 4: Decompose CLI main() Function ✅
+
+Extract these pure functions from `main()`:
+
+- `validateCliFlags()` - validate threshold and format flags ✅
+- `buildAnalyzerConfig()` - construct AnalyzerConfig from flags ✅
+- `handleAnalysisOutput()` - format and output results based on flags ✅
+- `buildThresholdConfig()` - extract threshold config from flags ✅
+- Refactor `main()` to orchestrate the extracted functions ✅
+- Add unit tests for extracted pure functions ✅
+
+Note: Pure functions extracted to `cli-utils.ts` to enable unit testing without triggering CLI entry point.
+
+Function signatures:
+```typescript
+function validateCliFlags(flags: CliFlags): 
+  { valid: true } | { valid: false; error: string }
+
+function buildAnalyzerConfig(
+  tsconfigPath: string, 
+  flags: CliFlags
+): AnalyzerConfig
+
+function buildThresholdConfig(flags: CliFlags): {
+  minHealth?: number
+  minPurity?: number
+  minQuality?: number
+}
+```
+
+### Phase 5: Add --files Glob Validation ✅
+
+- Add `validateGlobPattern()` function ✅
+- Integrate validation into CLI before analysis ✅
+- Add test for invalid glob patterns ✅
+- Display helpful error message for invalid patterns ✅
+
+Validation should catch:
+- Unbalanced brackets `[` or `{`
+- Empty pattern
+- Pattern starting with `/` (absolute paths not supported)
+
+### Phase 6: Documentation Updates ✅
+
+- Update TECHNICAL.md to remove fs-import from marker table ✅
+- Update README.md to remove fs-import from marker table ✅
+- Review and update any outdated documentation ✅
+
+## Tests
+
+### Unit Tests
+
+**`extractor.test.ts`** — Add test for extracted validation:
+```typescript
+describe('validateTsconfigContent', () => {
+  it('should return valid for correct JSONC', () => {
+    const result = validateTsconfigContent('{ "compilerOptions": {} }')
+    expect(result).toEqual({ valid: true })
+  })
+
+  it('should return error for invalid JSON', () => {
+    const result = validateTsconfigContent('{ invalid }')
+    expect(result.valid).toBe(false)
+    expect(result.error).toContain('Parse error')
+  })
+
+  it('should accept trailing commas', () => {
+    const result = validateTsconfigContent('{ "a": [1,], }')
+    expect(result).toEqual({ valid: true })
+  })
+})
+```
+
+**`cli.test.ts`** (new file) — Test extracted CLI functions:
+```typescript
+describe('validateCliFlags', () => {
+  it('should reject minHealth > 100', () => {
+    const result = validateCliFlags({ minHealth: 101 })
+    expect(result.valid).toBe(false)
+  })
+
+  it('should reject invalid format', () => {
+    const result = validateCliFlags({ format: 'xml' })
+    expect(result.valid).toBe(false)
+  })
+})
+
+describe('validateGlobPattern', () => {
+  it('should reject unbalanced brackets', () => {
+    const result = validateGlobPattern('src/[incomplete')
+    expect(result.valid).toBe(false)
+  })
+
+  it('should accept valid glob', () => {
+    const result = validateGlobPattern('src/**/*.ts')
+    expect(result).toEqual({ valid: true })
+  })
+})
+```
+
+## Transitive Effect Analysis
+
+### Phase 1 (tsconfig validation)
+- `cli.ts` → imports from `extractor.ts` ✓ (new import, no breaks)
+- `extractor.ts` → used by `analyzer.ts` ✓ (internal change, no breaks)
+- Tests: `extractor.test.ts` ✓ (add new tests)
+
+### Phase 2 (dead code removal)
+- `markers.ts` → imported by `detect-markers.ts` (only uses `MARKER_CATALOG`)
+- `markers.ts` → re-exported by `index.ts` (must update exports)
+- External consumers using removed exports would break (considered acceptable as they're unused internally)
+
+### Phase 3 (fs-import removal)
+- `types.ts` → imported everywhere (MarkerType narrowing)
+- `markers.ts` → MARKER_CATALOG type depends on MarkerType
+- `detect-markers.ts` → no longer detects fs-import (already true)
+- Tests checking for `fs-import` markers → update or remove
+
+### Phase 4 (CLI decomposition)
+- `cli.ts` → internal refactor only
+- No external consumers of CLI internals
+- New test file depends on extracted functions
+
+### Phase 5 (glob validation)
+- `cli.ts` → new validation step before `analyze()`
+- `extractor.ts` → no changes (glob passed through)
+
+## Resources for Implementation
+
+**Files to modify:**
+- `fcis/src/extraction/extractor.ts` — Phase 1
+- `fcis/src/cli.ts` — Phases 1, 4, 5
+- `fcis/src/detection/markers.ts` — Phases 2, 3
+- `fcis/src/types.ts` — Phase 3
+- `fcis/src/index.ts` — Phase 2 (update exports)
+- `fcis/TECHNICAL.md` — Phase 6
+
+**Files to create:**
+- `fcis/tests/cli.test.ts` — Phases 4, 5
+
+**Files to update tests:**
+- `fcis/tests/extractor.test.ts` — Phase 1
+- `fcis/tests/detect-markers.test.ts` — Phase 3 (if any fs-import tests exist)
+
+**Reference:**
+- Current `cli.ts` main() function structure
+- Current `markers.ts` export list
+- `jsonc-parser` API for validation
+
+## Documentation Updates
+
+### TECHNICAL.md
+
+Remove `fs-import` row from marker detection table:
+
+```markdown
+| Marker Type | Detection Pattern |
+|-------------|-------------------|
+| `await-expression` | Any `await` keyword in function body |
+| `database-call` | `db.*.findFirst`, `prisma.*.create`, etc. |
+| `network-fetch` | `fetch(...)` call |
+| `network-http` | `axios.*` call |
+| `fs-call` | `fs.readFile`, `fs.writeFile`, `readFile`, `writeFile`, etc. |
+...
+```
+
+(Remove the `fs-import` row that previously existed)

package/.plans/004-directory-depth-rollup.md

@@ -0,0 +1,408 @@
+# Plan 004: Directory Depth Rollup
+
+## Background
+
+The FCIS analyzer currently shows directory-level metrics at the leaf level (deepest directories containing files). When analyzing large codebases like `apps/web/src/server/**/*.ts`, this produces a long list of deeply nested directories that's hard to get a high-level overview from.
+
+Users want to see aggregate metrics for top-level directories (e.g., `src/agents`, `src/services`, `src/api`) to quickly identify which areas of the codebase need the most attention.
+
+## Problem Statement
+
+The current "Directories Needing Attention" output:
+1. Only shows directories with health < 70% (hides healthy directories)
+2. Limited to 5 directories
+3. Shows leaf directories, not aggregate rollups
+4. Doesn't give a holistic view of codebase health by area
+
+Users need a way to see ALL top-level directories with aggregate metrics to understand the health distribution across the codebase at a glance.
+
+## Success Criteria
+
+1. New `--dir-depth N` CLI flag controls directory aggregation depth
+2. When specified, directories are grouped by their Nth path segment relative to project root
+3. ALL directories at that depth are shown (not just failing ones)
+4. Metrics (health, purity, quality, function counts) are correctly aggregated
+5. Output is sorted alphabetically by path for easy scanning
+6. Default behavior (no flag) remains unchanged
+
+## The Gap
+
+| Aspect | Current State | Target State |
+|--------|---------------|--------------|
+| Directory display | Leaf directories only | Configurable depth rollup |
+| Filtering | Only health < 70% | Show all at specified depth |
+| Limit | Max 5 directories | Show all at specified depth |
+| Aggregation | Per-directory only | Hierarchical rollup |
+
+## Example Output
+
+With `--dir-depth 1`:
+
+```
+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
+```
+
+## Design Decisions
+
+### DD1: Extract shared aggregation logic
+
+Both `scoreDirectory()` and the new `rollupDirectoriesByDepth()` need to compute weighted averages for the same metrics. To avoid duplication, we'll extract a generic `aggregateMetrics()` helper that both can use.
+
+```typescript
+type Aggregatable = {
+  pureCount: number
+  impureCount: number
+  impurityQuality: number | null
+  statusBreakdown: StatusBreakdown
+  pureLineCount: number
+  impureLineCount: number
+  excludedCount: number
+}
+
+function aggregateMetrics<T extends Aggregatable>(items: T[]): Aggregatable
+```
+
+### DD2: Path handling strategy
+
+The codebase uses absolute paths internally (from `sourceFile.getFilePath()`). The rollup function needs to:
+1. Convert absolute paths to relative paths using `path.relative(projectRoot, absolutePath)`
+2. Parse depth using forward slashes (normalize Windows paths)
+3. Handle edge cases where directories are shallower than requested depth (keep as-is)
+
+We'll add a pure helper function:
+
+```typescript
+function getPathAtDepth(relativePath: string, depth: number): string {
+  const segments = relativePath.split('/').filter(Boolean)
+  if (depth >= segments.length) {
+    return relativePath // Can't truncate shallower than actual depth
+  }
+  return segments.slice(0, depth + 1).join('/')
+}
+```
+
+### DD3: DirectoryScore reuse for rolled-up directories
+
+For rolled-up directories, we'll reuse `DirectoryScore` with `fileScores: []`. This is pragmatic for MVP — semantically a rolled-up directory doesn't have direct files, but an empty array is unambiguous. We can revisit with a discriminated union type if needed later.
+
+### DD4: Rollup is a presentation concern
+
+The rollup happens in the **reporting layer**, not the analyzer. The `ProjectScore.directoryScores` always contains the full leaf-level data. The rollup is computed on-demand when displaying or generating JSON output with `--dir-depth`.
+
+This keeps the analyzer pure and allows JSON consumers to always get full data alongside rolled-up data.
+
+### DD5: JSON output includes both full and rolled-up data
+
+When `--dir-depth` is specified, JSON output will include:
+- `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.
+
+### DD6: Coupling depth with "show all"
+
+When `--dir-depth N` is specified, ALL directories at that depth are shown (no health < 70% filter). This coupling is intentional — the purpose of depth rollup is to get a holistic view, and filtering would defeat that purpose.
+
+## Phases and Tasks
+
+### Phase 0: Refactor aggregation logic ✅
+
+Extract shared aggregation logic from `scoreDirectory()` to enable reuse.
+
+- Create `aggregateMetrics()` helper function in `scorer.ts` ✅
+- Refactor `scoreDirectory()` to use the helper ✅
+- Refactor `scoreProject()` to use the helper ✅
+- Ensure all existing tests still pass ✅
+
+This is a pure refactoring phase — no behavior changes.
+
+### Phase 1: Add Directory Rollup Logic ✅
+
+- Add `getPathAtDepth()` path utility function to `scorer.ts` ✅
+- Add `rollupDirectoriesByDepth()` function to `scorer.ts` ✅
+- Function takes `DirectoryScore[]`, depth, and projectRoot; returns aggregated `DirectoryScore[]` ✅
+- Use `aggregateMetrics()` helper for weighted averages ✅
+- Add unit tests for path utility and rollup logic ✅
+
+Key function signatures:
+```typescript
+function getPathAtDepth(relativePath: string, depth: number): string
+
+function rollupDirectoriesByDepth(
+  directories: DirectoryScore[],
+  depth: number,
+  projectRoot: string
+): DirectoryScore[]
+```
+
+### Phase 2: Add CLI Flag ✅
+
+- Add `--dir-depth` flag to cleye configuration in `cli.ts` ✅
+- Add `dirDepth` to `CliFlags` type in `cli-utils.ts` ✅
+- Add validation using Zod: `z.number().int().min(1)` ✅
+- Pass depth through to reporter via options ✅
+- Add tests for flag validation ✅
+
+### Phase 3: Update Console Report ✅
+
+- Update `printConsoleReport()` signature to accept `dirDepth?: number` option ✅
+- Add `printRolledUpDirectories()` function for depth-based display ✅
+- When depth specified, call rollup and show all directories alphabetically ✅
+- Update table header to indicate depth: "Directory Breakdown (depth=N):" ✅
+- Preserve existing behavior when depth not specified ✅
+
+### Phase 4: Update JSON Report ✅
+
+- Add optional `rolledUpDirectories?: DirectoryScore[]` to `ProjectScore` type ✅
+- Update `generateJsonReport()` to accept depth option ✅
+- Compute and include rolled-up directories when depth specified ✅
+- Keep `directoryScores` unchanged (full data always present) ✅
+
+### Phase 5: Documentation ✅
+
+- Update README.md CLI reference with `--dir-depth` flag ✅
+- Update TECHNICAL.md with rollup algorithm description ✅
+- Add example output to README.md ✅
+
+## Tests
+
+### Unit Tests
+
+**`scorer.test.ts`** — Test path utility:
+
+```typescript
+describe('getPathAtDepth', () => {
+  it('should return first N+1 segments for depth N', () => {
+    expect(getPathAtDepth('src/services/auth/utils', 1)).toBe('src/services')
+    expect(getPathAtDepth('src/services/auth/utils', 2)).toBe('src/services/auth')
+  })
+
+  it('should return full path when depth exceeds segments', () => {
+    expect(getPathAtDepth('src/utils', 5)).toBe('src/utils')
+  })
+
+  it('should handle single segment paths', () => {
+    expect(getPathAtDepth('src', 0)).toBe('src')
+    expect(getPathAtDepth('src', 1)).toBe('src')
+  })
+})
+```
+
+**`scorer.test.ts`** — Test rollup logic:
+
+```typescript
+describe('rollupDirectoriesByDepth', () => {
+  it('should aggregate directories at depth 1', () => {
+    const dirs = [
+      createDirScore('/project/src/services/auth', { pureCount: 5, impureCount: 5 }),
+      createDirScore('/project/src/services/users', { pureCount: 3, impureCount: 7 }),
+      createDirScore('/project/src/utils/format', { pureCount: 8, impureCount: 2 }),
+    ]
+    
+    const rolled = rollupDirectoriesByDepth(dirs, 1, '/project')
+    
+    expect(rolled).toHaveLength(2)
+    expect(rolled.find(d => d.dirPath === 'src/services')?.pureCount).toBe(8)
+    expect(rolled.find(d => d.dirPath === 'src/utils')?.pureCount).toBe(8)
+  })
+
+  it('should calculate weighted health correctly', () => {
+    const dirs = [
+      createDirScore('/project/src/a', { 
+        pureCount: 10, impureCount: 0,  // 100% health, 10 functions
+        statusBreakdown: { ok: 10, review: 0, refactor: 0 }
+      }),
+      createDirScore('/project/src/b', { 
+        pureCount: 0, impureCount: 10,  // 0% health, 10 functions
+        statusBreakdown: { ok: 0, review: 0, refactor: 10 }
+      }),
+    ]
+    
+    const rolled = rollupDirectoriesByDepth(dirs, 0, '/project')
+    
+    // Weighted by function count: (10*100 + 10*0) / 20 = 50%
+    expect(rolled[0]?.health).toBe(50)
+  })
+
+  it('should handle depth greater than actual nesting', () => {
+    const dirs = [
+      createDirScore('/project/src', { pureCount: 5, impureCount: 5 }),
+    ]
+    
+    const rolled = rollupDirectoriesByDepth(dirs, 5, '/project')
+    
+    expect(rolled).toHaveLength(1)
+    expect(rolled[0]?.dirPath).toBe('src')
+  })
+
+  it('should return empty array for empty input', () => {
+    const rolled = rollupDirectoriesByDepth([], 1, '/project')
+    expect(rolled).toHaveLength(0)
+  })
+
+  it('should sort results alphabetically by path', () => {
+    const dirs = [
+      createDirScore('/project/z/deep', { pureCount: 1, impureCount: 1 }),
+      createDirScore('/project/a/deep', { pureCount: 1, impureCount: 1 }),
+      createDirScore('/project/m/deep', { pureCount: 1, impureCount: 1 }),
+    ]
+    
+    const rolled = rollupDirectoriesByDepth(dirs, 0, '/project')
+    
+    expect(rolled.map(d => d.dirPath)).toEqual(['a', 'm', 'z'])
+  })
+})
+```
+
+**`cli.test.ts`** — Test flag validation:
+
+```typescript
+describe('--dir-depth validation', () => {
+  it('should accept positive integer', () => {
+    const flags = createDefaultFlags({ dirDepth: 2 })
+    expect(validateCliFlags(flags)).toEqual({ valid: true })
+  })
+
+  it('should accept depth of 1', () => {
+    const flags = createDefaultFlags({ dirDepth: 1 })
+    expect(validateCliFlags(flags)).toEqual({ valid: true })
+  })
+
+  it('should reject zero', () => {
+    const flags = createDefaultFlags({ dirDepth: 0 })
+    expect(validateCliFlags(flags).valid).toBe(false)
+  })
+
+  it('should reject negative numbers', () => {
+    const flags = createDefaultFlags({ dirDepth: -1 })
+    expect(validateCliFlags(flags).valid).toBe(false)
+  })
+
+  it('should reject non-integers', () => {
+    const flags = createDefaultFlags({ dirDepth: 1.5 })
+    expect(validateCliFlags(flags).valid).toBe(false)
+  })
+
+  it('should accept undefined (flag not provided)', () => {
+    const flags = createDefaultFlags({ dirDepth: undefined })
+    expect(validateCliFlags(flags)).toEqual({ valid: true })
+  })
+})
+```
+
+## Transitive Effect Analysis
+
+### Phase 0 (Refactor)
+- `scorer.ts` → internal refactoring only, no API changes
+- All existing tests must pass unchanged
+
+### Phase 1 (Rollup Logic)
+- `scorer.ts` → new pure functions added, no breaking changes
+- Types remain unchanged (reusing `DirectoryScore` with empty `fileScores`)
+
+### Phase 2 (CLI Flag)
+- `cli.ts` → new flag, no breaking changes
+- `cli-utils.ts` → extend `CliFlags` type, new validation
+- `cli.test.ts` → add new tests
+
+### Phase 3 (Console Report)
+- `report-console.ts` → extended options object (backward compatible)
+- `cli.ts` → pass depth to reporter
+- Existing behavior preserved when depth not specified
+
+### Phase 4 (JSON Report)
+- `types.ts` → add optional `rolledUpDirectories` to `ProjectScore`
+- `report-json.ts` → extended options, include new field when present
+- External consumers of JSON may see new field (non-breaking, additive)
+
+## Resources for Implementation
+
+**Files to modify:**
+- `fcis/src/scoring/scorer.ts` — Phase 0, Phase 1
+- `fcis/src/cli.ts` — Phase 2
+- `fcis/src/cli-utils.ts` — Phase 2
+- `fcis/src/reporting/report-console.ts` — Phase 3
+- `fcis/src/reporting/report-json.ts` — Phase 4
+- `fcis/src/types.ts` — Phase 4
+- `fcis/README.md` — Phase 5
+- `fcis/TECHNICAL.md` — Phase 5
+
+**Files to add/update tests:**
+- `fcis/tests/scorer.test.ts` — Phase 0, Phase 1
+- `fcis/tests/cli.test.ts` — Phase 2
+
+**Reference:**
+- Existing `scoreDirectory()` function for aggregation pattern
+- Existing `printDirectoryBreakdown()` for output format
+- `DirectoryScore` type definition
+- `toRelativePath()` in `report-console.ts` for path handling pattern
+
+## Documentation Updates
+
+### README.md
+
+Add to CLI Reference:
+
+```markdown
+  --dir-depth <N>       Roll up directory metrics to depth N (e.g., 1 for top-level)
+```
+
+Add example:
+
+```markdown
+### Directory Rollup
+
+To see aggregate metrics for top-level directories:
+
+```bash
+fcis tsconfig.json --dir-depth 1
+```
+
+This shows ALL directories at the specified depth with aggregated metrics, providing a high-level overview of codebase health by area.
+```
+
+### TECHNICAL.md
+
+Add section:
+
+```markdown
+## Directory Rollup
+
+When `--dir-depth N` is specified, directory metrics are aggregated hierarchically:
+
+1. Absolute directory paths are converted to paths relative to the project root
+2. Paths are truncated 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
+```
+
+## Estimated Line Impact
+
+- Phase 0 (Refactor): ~40 lines changed in `scorer.ts`
+- Phase 1 (Rollup): ~60 lines added to `scorer.ts`, ~80 lines tests
+- Phase 2 (CLI): ~15 lines in `cli.ts`, ~20 lines in `cli-utils.ts`, ~30 lines tests
+- Phase 3 (Console): ~40 lines in `report-console.ts`
+- Phase 4 (JSON): ~15 lines in `report-json.ts`, ~5 lines in `types.ts`
+- Phase 5 (Docs): ~30 lines
+
+**Total: ~335 lines** — well under the 2000 line PR limit.