fcis 0.1.0 → 0.2.1

package/.plans/005-code-refinements.md

@@ -0,0 +1,210 @@
+# Plan 005: Code Refinements
+
+## Background
+
+Following the implementation of Plan 004 (Directory Depth Rollup), a code review identified several opportunities for simplification, reducing redundancy, and improving adherence to the Functional Core / Imperative Shell (FC/IS) pattern.
+
+The FCIS analyzer is designed to follow FC/IS principles itself, with `scorer.ts` documented as a "PURE module." However, the recent addition of `rollupDirectoriesByDepth()` introduced a `path` import that performs I/O-adjacent operations, breaking this contract.
+
+Additionally, several patterns are repeated throughout the codebase that could be consolidated for maintainability.
+
+## Problem Statement
+
+1. **FC/IS violation:** `scorer.ts` imports `node:path` and uses `path.relative()` in `rollupDirectoriesByDepth()`, violating its documented pure module contract
+2. **Duplicate color logic:** Health/purity/quality color selection is repeated 6+ times in `report-console.ts`
+3. **Duplicate empty-case handling:** `rollupDirectoriesByDepth()` manually constructs empty metrics instead of reusing `aggregateMetrics([])`
+4. **Similar directory printing functions:** `printDirectoryBreakdown()` and `printRolledUpDirectories()` share nearly identical structure
+
+## Success Criteria
+
+1. `scorer.ts` has no `node:path` import — path relativization happens in the shell layer
+2. A single `getMetricColor()` function replaces all repeated color logic
+3. Empty directory metrics use `aggregateMetrics([])` for consistency
+4. Directory printing functions are unified into a single parameterized function
+5. All existing tests continue to pass
+6. No regression in CLI behavior
+
+## The Gap
+
+| Aspect | Current State | Target State |
+|--------|---------------|--------------|
+| `scorer.ts` purity | Imports `node:path` | Pure module, no I/O imports |
+| Color logic | Repeated 6+ times | Single reusable function |
+| Empty metrics | Manual construction | Uses `aggregateMetrics([])` |
+| Directory printing | Two similar functions | Single unified function |
+
+## Phases and Tasks
+
+### Phase 1: Extract Color Helper ✅
+
+- Create `getMetricColor()` function in `report-console.ts` ✅
+- Create `getMetricColorNullable()` for nullable values ✅
+- Replace all repeated color logic with helper calls ✅
+- Verify console output unchanged ✅
+
+Function signatures:
+```typescript
+type ChalkFn = typeof chalk.green
+
+function getMetricColor(value: number): ChalkFn
+
+function getMetricColorNullable(value: number | null): ChalkFn
+```
+
+### Phase 2: Unify Directory Printing ✅
+
+- Create unified `printDirectoryTable()` function ✅
+- Define `DirectoryTableOptions` type for configuration ✅
+- Refactor `printDirectoryBreakdown()` to use unified function ✅
+- Refactor `printRolledUpDirectories()` to use unified function ✅
+- Verify console output unchanged ✅
+
+Type definition:
+```typescript
+type DirectoryTableOptions = {
+  title: string
+  includeQualityColumn: boolean
+  sortBy: 'health-asc' | 'alphabetical'
+  emptyMessage?: string
+}
+```
+
+### Phase 3: Move Path Relativization to Shell ✅
+
+- Remove `path` import from `scorer.ts` ✅
+- Modify `rollupDirectoriesByDepth()` to accept pre-relativized paths ✅
+- Create helper in `report-console.ts` to relativize paths before calling rollup ✅
+- Update `report-json.ts` similarly ✅
+- Update tests to use relative paths directly ✅
+
+New function signature:
+```typescript
+// scorer.ts - now pure, expects relative paths in input
+export function rollupDirectoriesByDepth(
+  directories: DirectoryScore[],
+  depth: number,
+): DirectoryScore[]
+
+// report-console.ts - shell helper
+function relativizeDirectoryPaths(
+  directories: DirectoryScore[],
+  projectRoot: string,
+): DirectoryScore[]
+```
+
+### Phase 4: Use aggregateMetrics for Empty Case ✅
+
+- Replace manual empty metrics construction in `rollupDirectoriesByDepth()` ✅
+- Use `aggregateMetrics([])` spread with `dirPath` and `fileScores` overrides ✅
+- Verify behavior unchanged with existing tests ✅
+
+### Phase 5: Documentation ✅
+
+- Update TECHNICAL.md to reflect refactored architecture ✅
+- Verify `scorer.ts` header comment still accurate ✅
+
+## Tests
+
+### Existing Tests
+
+All changes are refactoring — existing tests in `scorer.test.ts` should continue to pass without modification. The tests for `rollupDirectoriesByDepth()` may need minor updates to pass relative paths instead of absolute paths.
+
+### New Tests
+
+No new test files needed. Verify:
+
+1. **Color helper:** Visual inspection of CLI output
+2. **Unified printing:** Visual inspection of CLI output
+3. **Path relativization:** Update existing `rollupDirectoriesByDepth` tests to use relative paths
+
+### Test Modifications
+
+```typescript
+// scorer.test.ts - update rollup tests to use relative paths
+describe('rollupDirectoriesByDepth', () => {
+  it('should aggregate directories at depth 1', () => {
+    const dirs = [
+      // Before: createDirScoreForRollup('/project/src/services/auth', ...)
+      // After: paths are already relative
+      createDirScoreForRollup('src/services/auth', ...),
+      createDirScoreForRollup('src/services/users', ...),
+      createDirScoreForRollup('src/utils/format', ...),
+    ]
+    
+    // Before: rollupDirectoriesByDepth(dirs, 1, '/project')
+    // After: no projectRoot parameter
+    const rolled = rollupDirectoriesByDepth(dirs, 1)
+    // ... assertions unchanged
+  })
+})
+```
+
+## Transitive Effect Analysis
+
+### Phase 1 (Color Helper)
+- `report-console.ts` → internal refactoring only
+- No external API changes
+- No transitive effects
+
+### Phase 2 (Unified Printing)
+- `report-console.ts` → internal refactoring only
+- No external API changes
+- No transitive effects
+
+### Phase 3 (Path Relativization)
+- `scorer.ts` → **API change**: `rollupDirectoriesByDepth()` signature changes
+- `report-console.ts` → must call new helper before rollup
+- `report-json.ts` → must call new helper before rollup
+- `scorer.test.ts` → must update test data to use relative paths
+- No external consumers affected (rollup is internal)
+
+### Phase 4 (Empty Case)
+- `scorer.ts` → internal refactoring
+- No API changes
+- No transitive effects
+
+## Resources for Implementation
+
+**Files to modify:**
+- `fcis/src/scoring/scorer.ts` — Phase 3, Phase 4
+- `fcis/src/reporting/report-console.ts` — Phase 1, Phase 2, Phase 3
+- `fcis/src/reporting/report-json.ts` — Phase 3
+- `fcis/tests/scorer.test.ts` — Phase 3
+
+**Reference:**
+- Current `rollupDirectoriesByDepth()` implementation
+- Current `printDirectoryBreakdown()` and `printRolledUpDirectories()` implementations
+- `aggregateMetrics()` empty case return value
+
+## Documentation Updates
+
+### TECHNICAL.md
+
+Update the architecture diagram description to note:
+- `scorer.ts` is a pure module with no I/O dependencies
+- Path relativization happens in the shell layer before calling scoring functions
+
+### scorer.ts Header
+
+Verify the header comment still accurately describes the module:
+```typescript
+/**
+ * Scoring Engine - Pure Core
+ *
+ * Aggregates classification and quality scores into metrics at
+ * file, directory, and project levels. This is a PURE module -
+ * all functions take data in and return data out with no I/O.
+ */
+```
+
+## Estimated Line Impact
+
+- Phase 1 (Color Helper): ~-20 lines (net reduction)
+- Phase 2 (Unified Printing): ~-40 lines (net reduction)
+- Phase 3 (Path Relativization): ~+10 lines (moves code, slight increase)
+- Phase 4 (Empty Case): ~-10 lines (net reduction)
+- Phase 5 (Documentation): ~5 lines
+
+**Total: ~-55 lines** — net simplification
+
+This is well under the 2000 line PR limit.

package/.plans/006-minor-refinements.md

@@ -0,0 +1,149 @@
+# Plan 006: Minor Refinements
+
+## Background
+
+Following the implementation of Plan 005 (Code Refinements), a code review identified three minor issues:
+
+1. **Misleading `sortBy` option name:** The `DirectoryTableOptions.sortBy` type includes `'alphabetical'`, but the implementation actually preserves input order rather than sorting alphabetically.
+
+2. **Inconsistent empty case handling:** `rollupDirectoriesByDepth()` now uses `aggregateMetrics([])` for empty groups, but `scoreDirectory()` and `scoreProject()` still manually construct empty metrics inline.
+
+3. **Untested shell helper:** The `relativizeDirectoryPaths()` function in `report-console.ts` has no direct unit tests.
+
+## Problem Statement
+
+1. The `sortBy: 'alphabetical'` option is misleading — it implies active sorting but actually means "preserve input order"
+2. Empty metric construction is inconsistent across scoring functions, increasing maintenance burden
+3. `relativizeDirectoryPaths()` is only tested indirectly through CLI integration tests
+
+## Success Criteria
+
+1. `sortBy` option renamed to `'preserve-order'` with accurate documentation
+2. `scoreDirectory()` and `scoreProject()` use `aggregateMetrics([])` for empty cases
+3. `relativizeDirectoryPaths()` has focused unit tests
+4. All existing tests continue to pass
+
+## The Gap
+
+| Aspect | Current State | Target State |
+|--------|---------------|--------------|
+| `sortBy` naming | `'alphabetical'` (misleading) | `'preserve-order'` (accurate) |
+| Empty metrics in `scoreDirectory` | Manual construction | Uses `aggregateMetrics([])` |
+| Empty metrics in `scoreProject` | Manual construction | Uses `aggregateMetrics([])` |
+| `relativizeDirectoryPaths` tests | None | Focused unit tests |
+
+## Phases and Tasks
+
+### Phase 1: Rename sortBy Option ✅
+
+- Rename `'alphabetical'` to `'preserve-order'` in `DirectoryTableOptions` type ✅
+- Update call site in `printConsoleReport()` ✅
+- Update comment to accurately describe behavior ✅
+
+Type change:
+```typescript
+type DirectoryTableOptions = {
+  title: string
+  includeQualityColumn: boolean
+  sortBy: 'health-asc' | 'preserve-order'  // was 'alphabetical'
+  emptyMessage?: string
+}
+```
+
+### Phase 2: Unify Empty Metrics Construction ✅
+
+- Refactor `scoreDirectory()` empty case to use `aggregateMetrics([])` ✅
+- Refactor `scoreProject()` empty case to use `aggregateMetrics([])` ✅
+- Verify existing tests still pass ✅
+
+### Phase 3: Add relativizeDirectoryPaths Tests ✅
+
+- Export `relativizeDirectoryPaths()` for testing (or test via module internals) ✅
+- Add unit tests for path relativization ✅
+- Test cross-platform path handling (backslash normalization) ✅
+
+## Tests
+
+### Phase 1 Tests
+
+No new tests needed — existing tests verify behavior, only the name changes.
+
+### Phase 2 Tests
+
+Existing tests in `scorer.test.ts` cover empty cases. Verify they still pass.
+
+### Phase 3 Tests
+
+Add to a new or existing test file:
+
+```typescript
+describe('relativizeDirectoryPaths', () => {
+  it('should convert absolute paths to relative paths', () => {
+    const dirs = [
+      { dirPath: '/project/src/services', ...otherProps },
+      { dirPath: '/project/src/utils', ...otherProps },
+    ]
+    const result = relativizeDirectoryPaths(dirs, '/project')
+    expect(result[0]?.dirPath).toBe('src/services')
+    expect(result[1]?.dirPath).toBe('src/utils')
+  })
+
+  it('should normalize backslashes to forward slashes', () => {
+    const dirs = [{ dirPath: 'C:\\project\\src', ...otherProps }]
+    const result = relativizeDirectoryPaths(dirs, 'C:\\project')
+    expect(result[0]?.dirPath).toBe('src')
+  })
+
+  it('should preserve other directory properties', () => {
+    const dirs = [{ dirPath: '/project/src', pureCount: 5, impureCount: 3, ...otherProps }]
+    const result = relativizeDirectoryPaths(dirs, '/project')
+    expect(result[0]?.pureCount).toBe(5)
+    expect(result[0]?.impureCount).toBe(3)
+  })
+})
+```
+
+## Transitive Effect Analysis
+
+### Phase 1 (sortBy Rename)
+- `report-console.ts` → internal type and call site change
+- No external API changes
+- No transitive effects
+
+### Phase 2 (Empty Metrics)
+- `scorer.ts` → internal refactoring
+- Behavior unchanged (same default values)
+- Existing tests verify correct output
+- No transitive effects
+
+### Phase 3 (relativizeDirectoryPaths Tests)
+- `report-console.ts` → may need to export function for testing
+- Alternative: test via integration or keep as private with indirect coverage
+- No production code changes needed if testing via integration
+
+## Resources for Implementation
+
+**Files to modify:**
+- `fcis/src/reporting/report-console.ts` — Phase 1, Phase 3
+- `fcis/src/scoring/scorer.ts` — Phase 2
+
+**Files to add/update tests:**
+- `fcis/tests/report-console.test.ts` (new) — Phase 3
+- Or `fcis/tests/scorer.test.ts` — verify Phase 2
+
+**Reference:**
+- Current `DirectoryTableOptions` type definition
+- Current `scoreDirectory()` and `scoreProject()` empty case handling
+- Current `relativizeDirectoryPaths()` implementation
+
+## Documentation Updates
+
+No documentation updates needed — these are internal implementation details not exposed in README or TECHNICAL.md.
+
+## Estimated Line Impact
+
+- Phase 1 (sortBy Rename): ~5 lines changed
+- Phase 2 (Empty Metrics): ~20 lines changed (net reduction)
+- Phase 3 (Tests): ~30 lines added
+
+**Total: ~55 lines** — well under the 2000 line PR limit.