# Plan: Radically Optimize the `em` Command

## Context

The `em` command displays SEC earnings data for companies. Currently, the codebase shows 35 compiler warnings, most of which are dead code in `src/terminal/sec_edgar/facts.rs`. This dead code exists because the codebase has migrated from a CompanyFacts-based approach to a filing-native XBRL approach, leaving behind unused functions and constants.

**Active Code Path for `em` command:**
```
command_service.rs::earnings()
  → load_earnings_data() in earnings/mod.rs
    → catalog::load_candidate_filings()
    → package::load_filing_package() [uses parse_filing_xbrl_instance]
    → dei::extract_period_identity() [uses find_text_fact]
    → mapper::map_filing_to_record()
    → build_panel_data()
```

**Other active SEC commands:**
- `/fin` (financials) - uses CompanyFacts approach via `build_statement_periods`
- `/cf` (cash flow) - uses CompanyFacts approach via `build_cash_flow_periods`
- `/div` (dividends) - uses CompanyFacts approach via `build_dividend_events`

## Problem Summary

1. **Unused CompanyFacts earnings functions** - The earnings command no longer uses these, but they remain
2. **Unused utility functions** - Helper functions only used by the dead earnings code
3. **Duplicate `month_abbreviation` function** - Exists in both `facts.rs` and `dei.rs`
4. **Unused variable warning** - `period_start` in `dei.rs` line 20

## Implementation Plan

### Step 1: Remove Dead CompanyFacts Earnings Code from `facts.rs`

**Remove these unused functions (lines 503-809):**
- `build_earnings_periods()`
- `build_earnings_period_rows()`
- `build_earnings_period_options()`
- `earnings_period_key_for_values()`
- `earnings_period_token_for_values()`
- `earnings_display_label_for_values()`
- `build_earnings_periods_from_rows()`

**Remove unused utility functions (lines 1014, 1037-1199):**
- `month_abbreviation()` (duplicate - dei.rs has its own)
- `duration_value_for_period()`
- `instant_value_for_period()`
- `difference()`
- `sum_values()`
- `subtract_many()`
- `calculate_ratio_percent()`
- `normalize_percent_value()`
- `calculate_change_percent()`

**Simplify OverlayPeriodKind enum (lines 1095-1100):**
- Remove unused `Duration` and `Instant` variants
- Keep only `Any` variant which is actively used

**Remove test helpers (lines 1497-1587):**
- Remove test-only functions that were only used by the dead code tests

### Step 2: Fix Unused Variable Warning in `dei.rs`

**Line 20 in `src/terminal/sec_edgar/earnings/dei.rs`:**
- Change `period_start: &str` to `_period_start: &str`

### Step 3: Add Module Documentation

Add clear module-level documentation to explain the two approaches:
- `facts.rs` - CompanyFacts-based approach (used by `/fin`, `/cf`, `/div`)
- `earnings/` module - Filing-native approach (used by `/em`)

## Critical Files to Modify

1. **`src/terminal/sec_edgar/facts.rs`** - Remove ~400 lines of dead code
2. **`src/terminal/sec_edgar/earnings/dei.rs`** - Fix unused variable

## What Will NOT Be Removed

The following ARE actively used and must be preserved:
- `normalize_all_facts()` - Used by `/fin`, `/cf`, `/div`
- `build_statement_periods()` - Used by `/fin`
- `build_cash_flow_periods()` - Used by `/cf`
- `build_dividend_events()` - Used by `/div`
- `build_source_status()`, `company_name()`, `limit_dividend_ttm()`, `select_latest_filing()`, `default_earnings_period_limit()`
- All concept constants used by the above functions
- `parse_filing_xbrl_instance()`, `FilingXbrlDocument` - Used by earnings module
- `find_text_fact()` - Used by dei.rs
- `classify_fact_unit_family()`, `FilingContext`, `FilingFact` - Used by mapper

## Verification

After implementing these changes:

1. **Run `cargo build`** - All 35 warnings should be eliminated
2. **Run `cargo test`** - All tests should pass
3. **Test `em` command** - `/em AAPL` should work correctly
4. **Test other SEC commands** - `/fin AAPL`, `/cf AAPL`, `/div KO` should work correctly
5. **Run `bun run tauri dev`** - Application should compile and run without warnings

## Expected Outcome

- **0 compiler warnings** (down from 35)
- **~400 lines removed** from facts.rs
- **Cleaner, more maintainable codebase** with single-purpose functions
- **No breaking changes** to any existing functionality
