#!/bin/bash
# Examine src/main.rs to identify CLI-only logic vs potentially shared functionality
echo "=== src/main.rs structure ==="
cat src/main.rs | head -100

echo -e "\n=== Functions in src/main.rs ==="
ast-grep --pattern $'fn $FUNC($$$) {
  $$$
}' src/main.rs | head -50

#!/bin/bash
# Check src/lib.rs for current public API exports
echo "=== src/lib.rs public API ==="
cat src/lib.rs

echo -e "\n=== All public functions, structs, enums in lib.rs ==="
rg -n "^pub " src/lib.rs

#!/bin/bash
# Look for conversion and export logic across the codebase
echo "=== Conversion module ==="
cat src/conversion.rs | head -80

echo -e "\n=== Export functions locations ==="
rg -n "pub fn export_to_" --type=rust

echo -e "\n=== ExportOptions definition ==="
rg -n -A 10 "pub struct ExportOptions" --type=rust

#!/bin/bash
# Check issue #27 details
echo "=== Issue #27 details ==="
gh issue view 27 --json title,body,state,labels,comments --jq '.title, .body, .state, .labels[].name, .comments[].body'

#!/bin/bash
# Look for any remaining TODOs or FIXME comments in the codebase
echo "=== TODOs and FIXMEs ==="
rg -n "TODO|FIXME" --type=rust

echo -e "\n=== Check for duplication patterns between main.rs and library ==="
rg -n "compute_export_paths|print_export_message" --type=rust

#!/bin/bash
# Get a complete list of functions in src/main.rs to analyze what's CLI-only vs potentially shared
echo "=== All functions in src/main.rs ==="
ast-grep --pattern $'fn $FUNC($$$) $$$' src/main.rs | rg "^src/main.rs:" | head -50

echo -e "\n=== Check main.rs structure - count lines and key sections ==="
wc -l src/main.rs
rg -n "^fn " src/main.rs | wc -l
echo "Total functions found"

echo -e "\n=== Look for any display or formatting functions ==="
rg -n "^fn (display|format|print)" src/main.rs

#!/bin/bash
# Check if there's any logic in main.rs that deals with data transformation that might belong in library
echo "=== Check for data processing in main.rs ==="
rg -n "fn process|fn parse|fn convert" src/main.rs

echo -e "\n=== Check what the CLI does with BBLLog after parsing ==="
rg -n -A 5 "parse_bbl_file|BBLLog" src/main.rs | head -80

echo -e "\n=== Check if there are any helper functions that might be useful in library ==="
rg -n "^fn [a-z_]+.*\) -> " src/main.rs | head -30

#!/bin/bash
# Look at the export.rs module to understand the current state and what Item #3 and #5 would involve
echo "=== Early-return logic in export functions ==="
rg -n -B 3 -A 3 "gps_coordinates.is_empty|events.is_empty" src/export.rs

echo -e "\n=== Current return types of export functions ==="
rg -n "^pub fn export_to_.*\) -> " src/export.rs

#!/bin/bash
# Check if there's any information about what Phase 6 or future phases might entail
echo "=== Search for Phase references in issues ==="
gh issue list --state all --limit 50 --json number,title,body,state | jq -r '.[] | select(.title | contains("Phase")) | "\(.number): \(.title) [\(.state)]"'

echo -e "\n=== Check for any architectural decision documentation ==="
fd -e md . | head -20
cat AGENTS.md 2>/dev/null || echo "AGENTS.md not found"

#!/bin/bash
# Check the current test coverage and structure
echo "=== Test files in the repository ==="
fd -e rs -p tests/

echo -e "\n=== Tests in src/main.rs ==="
rg -n "^#\[test\]|^#\[cfg\(test\)\]" src/main.rs | wc -l
echo "test markers found in main.rs"

echo -e "\n=== Check if there are unit tests in other modules ==="
rg -n "^#\[cfg\(test\)\]" --type=rust | head -20

#!/bin/bash
# Check if there's parsing logic duplication between main.rs and library
echo "=== Parsing functions in main.rs ==="
rg -n -A 10 "^fn parse_bbl_file\(" src/main.rs

echo -e "\n=== Parsing functions in library ==="
rg -n "pub fn parse_bbl" src/parser/*.rs src/lib.rs

echo -e "\n=== Check parse_bbl_file_streaming in main.rs ==="
rg -n -A 20 "^fn parse_bbl_file_streaming\(" src/main.rs

#!/bin/bash
# Look for export heuristics and see if they're only in main.rs
echo "=== Export skip/filter heuristics ==="
rg -n -A 5 "fn should_skip_export|fn has_minimal_gyro_activity" src/main.rs

echo -e "\n=== Check if ExportOptions has any filter/skip settings ==="
rg -n -A 20 "pub struct ExportOptions" src/export.rs

#!/bin/bash
# Create a detailed issue for remaining work
cat > /tmp/issue_body.md << 'EOF'
## Summary

With PR #32 merged, **issue #27 is now complete** (library export integration tests added). However, to fully achieve the goals of de-duplication and functionality migration for dual CLI and CRATE usage, several important follow-up items remain.

This issue outlines a **detailed iterative plan** to complete the library/CLI separation and ensure all crate-consumer-useful functionality is properly exposed.

## Context

**Current Achievement Status:**
- ✅ Phase 1-3: Parser and conversion utilities unified (issue #11)
- ✅ Phase 4: Frame parsers unified (issue #13)  
- ✅ Phase 5: Types, main parser, and export functions unified (issue #16)
- ✅ Issue #27 (Phase 5 follow-up): Export integration tests, GPX directory creation, naming consistency (**completed with PR #32**)

**Architecture Baseline:**
- `src/lib.rs`: Public API with re-exports from all modules
- `src/main.rs`: CLI entry point (~1405 lines, 15 functions)
- Export functions (`export_to_csv`, `export_to_gpx`, `export_to_event`) are in library
- CLI uses library functions with CLI-specific status messages

**Retrieved Learning:**
> Decision criteria: "Is this needed by crate consumers?" determines placement — shared logic in library, CLI-only logic in `src/main.rs`

## Remaining Work

### Phase 6: Finalize Library API and Eliminate Remaining Duplication

#### Item 1: Audit and resolve parsing function duplication ⚠️ HIGH PRIORITY

**Problem:** `src/main.rs` contains functions named `parse_bbl_file()` and `parse_single_log()` that may duplicate or diverge from library parsing functions.

**Investigation needed:**
- Compare `main.rs::parse_bbl_file()` (line 481) with library's `parse_bbl_file()` 
- Check if `main.rs::parse_single_log()` (line 554) is CLI-specific or should be in library
- Verify `main.rs::parse_bbl_file_streaming()` (line 1004) - streaming API for library?

**Expected outcome:**
- CLI uses library parsing functions exclusively
- No duplicate parsing logic in `main.rs`
- If streaming API is valuable for crate consumers, expose it in library
- Document any CLI-specific parsing wrappers and their purpose

**Acceptance criteria:**
- No function name collisions between `main.rs` and library
- `main.rs` imports and uses library parsing functions
- Streaming export capability is properly exposed (if library-worthy)

---

#### Item 2: Evaluate export heuristics for library inclusion 🔍 MEDIUM PRIORITY

**Problem:** `src/main.rs` contains export skip/filter heuristics that might be useful for library consumers:
- `should_skip_export()` (line 854) - skips very short flights or minimal gyro activity
- `has_minimal_gyro_activity()` (line 929) - detects ground tests
- `calculate_variance()` (line 993) - statistical helper

**Question:** Should these be:
1. CLI-only features (stay in `main.rs`), OR
2. Optional library features via `ExportOptions`?

**Investigation needed:**
- Would crate consumers benefit from configurable export filtering?
- Should `ExportOptions` gain fields like `skip_short_flights: bool`, `min_duration_ms: Option<u64>`, `skip_ground_tests: bool`?
- Consider privacy: some users may want ALL data, others may want filtered exports

**Proposed solution:**
- Add optional filter settings to `ExportOptions` with sensible defaults
- Move heuristic functions to library (e.g., `src/export.rs` or new `src/filters.rs`)
- CLI enables filters by default; library consumers can opt in/out
- Keep CLI-specific messaging in `main.rs`

**Acceptance criteria:**
- Export filtering is either explicitly marked CLI-only OR moved to library with proper configuration
- No silent filtering behavior surprises library consumers
- CLI maintains current filtering behavior via library options

---

#### Item 3: Implement ExportReport return type (from issue #27, Item #5) 📋 MEDIUM PRIORITY

**Problem:** Export functions currently return `Result<()>`, making it impossible for callers to know which files were actually created.

**Proposed enhancement:**
```rust
pub struct ExportReport {
    pub csv_path: Option<PathBuf>,
    pub headers_path: Option<PathBuf>,
    pub gpx_path: Option<PathBuf>,
    pub event_path: Option<PathBuf>,
}

pub fn export_to_csv(...) -> Result<ExportReport> { ... }
pub fn export_to_gpx(...) -> Result<ExportReport> { ... }
pub fn export_to_event(...) -> Result<ExportReport> { ... }
```

**Benefits:**
- Library consumers can log exact paths written
- CLI can print precise export messages without recomputing paths
- Enables post-export validation and testing
- Reduces coupling between path computation and CLI messaging

**Implementation plan:**
1. Define `ExportReport` struct in `src/export.rs`
2. Update export functions to return `Result<ExportReport>`
3. Update CLI to use returned paths for status messages
4. Update integration tests to validate returned paths
5. Add documentation examples

**Acceptance criteria:**
- Export functions return actual paths written
- CLI prints exact paths from `ExportReport`
- Integration tests verify `ExportReport` accuracy
- Breaking change documented in CHANGELOG

---

#### Item 4: Early-return cleanup (from issue #27, Item #3) 🔧 LOW PRIORITY

**Current state:** Export functions have early-returns for empty data (e.g., `gps_coordinates.is_empty()`), but path computation happens before the check.

**Proposed cleanup:**
- Move early-return checks to the very top of export functions
- Avoid computing paths when no export will happen
- Ensure CLI messaging still works correctly

**Implementation:**
```rust
pub fn export_to_gpx(...) -> Result<ExportReport> {
    // Early return BEFORE path computation
    if gps_coordinates.is_empty() {
        return Ok(ExportReport::default());
    }
    
    // Now compute paths only if exporting
    let paths = compute_export_paths(...);
    // ... rest of export logic
}
```

**Acceptance criteria:**
- Early-returns happen before path computation
- CLI messages remain correct (use `compute_export_paths()` for display)
- No performance impact on actual exports
- Integration tests pass

---

#### Item 5: Public API audit and refinement 🏗️ MEDIUM PRIORITY

**Problem:** `src/lib.rs` currently re-exports everything with `pub use module::*`, which may expose internal implementation details.

**Investigation needed:**
- Review what should be public vs. internal
- Check for unintentional public API surface (e.g., internal helpers)
- Verify consistency with documented public API in learnings:
  > Public API must expose: `parse_bbl_file()`, `parse_bbl_bytes()`, `BBLLog`, `ExportOptions`, `export_to_csv()`, `export_to_gpx()`, `export_to_event()`, conversion utilities, parser helpers

**Proposed changes:**
- Replace wildcard re-exports with explicit item lists
- Mark internal helpers with `pub(crate)` visibility
- Document public API in `src/lib.rs` with examples
- Consider creating a prelude module for common imports

**Example refinement:**
```rust
// Instead of:
pub use export::*;

// Use explicit exports:
pub use export::{
    ExportOptions, ExportReport,
    export_to_csv, export_to_gpx, export_to_event,
    compute_export_paths,
};
```

**Acceptance criteria:**
- Only intended public items are exported
- Internal helpers use `pub(crate)` or private visibility
- Documentation clearly lists the public API
- No breaking changes for existing consumers (if possible)

---

#### Item 6: Documentation completeness 📚 MEDIUM PRIORITY

**Current state:** Documentation exists in `README.md`, `CRATE_USAGE.md`, and `examples/README.md`, recently enhanced by PR #32.

**Additional needs:**
- API reference documentation in rustdoc comments
- Ensure all public functions have doc comments with examples
- Document feature flags and their impact on API
- Add crate-level documentation to `src/lib.rs`

**Tasks:**
1. Add `//!` module-level docs to `src/lib.rs` with:
   - Feature flag table
   - Quick start example
   - Link to examples and CRATE_USAGE.md
2. Ensure every public function has `///` doc comments
3. Add doc examples that are tested with `cargo test --doc`
4. Document error types and recovery strategies

**Acceptance criteria:**
- `cargo doc --open` produces comprehensive API documentation
- All public items have rustdoc comments
- Doc examples compile and run successfully
- Feature flags are clearly documented

---

#### Item 7: CLI reduction and simplification 🔨 LOW PRIORITY

**Current state:** CLI is ~1405 lines (down from ~1800 after unification).

**Opportunities:**
- If Items 1-2 move more logic to library, CLI may shrink further
- Simplify CLI functions to thin wrappers around library calls
- Review if any CLI helper functions have general utility

**Investigation needed:**
- Can `expand_input_paths()` (glob/directory handling) be useful in library?
- Are display functions (`display_frame_data`, `display_debug_info`) properly isolated?
- Should `should_have_frame()` (line 250) be in library?

**Proposed approach:**
1. After Items 1-2 complete, audit remaining `main.rs` functions
2. Move any general-purpose helpers to library
3. Keep pure CLI concerns (arg parsing, output formatting) in `main.rs`
4. Target: CLI under 1000 lines if possible

**Acceptance criteria:**
- CLI is minimal wrapper around library
- No general-purpose logic remains CLI-only
- CLI tests remain comprehensive
- CLI behavior unchanged for end users

---

## Implementation Order

**Recommended iteration sequence:**

1. **Iteration 1 (Critical):** Item 1 - Resolve parsing duplication
   - Ensures foundation is solid before other changes
   - Prevents divergent implementations

2. **Iteration 2 (Enhancement):** Item 3 - Implement ExportReport
   - Provides better API before Item 4 cleanup
   - Enables better testing and validation

3. **Iteration 3 (Cleanup):** Item 4 - Early-return cleanup
   - Builds on Item 3's ExportReport structure
   - Minor polish with low risk

4. **Iteration 4 (Features):** Item 2 - Export heuristics evaluation
   - After core API is stable (Items 1, 3, 4)
   - Decision-heavy; may need community input

5. **Iteration 5 (Polish):** Item 5 - Public API audit
   - After all functionality is in place
   - Ensures clean API surface

6. **Iteration 6 (Documentation):** Item 6 - Documentation completeness
   - After API is finalized
   - Prepares for stable release

7. **Iteration 7 (Optimization):** Item 7 - CLI reduction
   - Final cleanup after all library work
   - Non-critical quality improvement

---

## Testing Strategy

For each iteration:
- Run full test suite: `cargo test --verbose`
- Run CLI tests: `cargo test --features=cli --verbose`
- Run integration tests: `cargo test --test export_integration_tests`
- Verify Clippy: `cargo clippy --all-targets --all-features -- -D warnings`
- Check formatting: `cargo fmt --all -- --check`
- Build release: `cargo build --release`

---

## Success Criteria

**Overall goals achieved when:**
- ✅ No parsing logic duplication between CLI and library
- ✅ All crate-consumer-useful functionality is in library
- ✅ CLI is minimal wrapper with only CLI-specific logic
- ✅ Export functions return actionable results (ExportReport)
- ✅ Public API is clean, well-documented, and intentional
- ✅ Export filtering is either explicitly CLI-only or library-configurable
- ✅ Comprehensive documentation in rustdoc and examples
- ✅ All tests pass across platforms
- ✅ No clippy warnings or formatting issues

---

## Related Issues

- #11 - Phase 1-3 unification (CLOSED)
- #13 - Phase 4 frame parsers (CLOSED)
- #16 - Phase 5 types and export (CLOSED)
- #27 - Phase 5 follow-up tests/docs (CLOSED via #28, #32)

---

## Notes

- This is an **iterative plan** - each item can be addressed in a separate PR
- Items can be reordered based on priority and dependencies
- Some items may be marked "CLI-only" after discussion rather than moved to library
- Breaking changes (e.g., ExportReport) should be versioned appropriately
- Community feedback welcome on Item 2 (export heuristics) and Item 5 (public API)

---

**Requested by:** @nerdCopter
**Date:** 2025-12-19
EOF

echo "=== Creating new issue ==="
gh issue create \
  --title "Phase 6: Complete library/CLI separation and API finalization" \
  --body-file /tmp/issue_body.md \
  --label "enhancement" \
  --label "documentation"

echo -e "\n=== Issue created successfully ==="

Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-13T15:51:00.137Z
Learning: Decision criteria: 'Is this needed by crate consumers?' determines placement — shared logic in library, CLI-only logic in `src/main.rs`

Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: LICENSE_COMMERCIAL:1-4
Timestamp: 2025-08-29T19:52:05.099Z
Learning: nerdCopter prefers to avoid publishing personal information in license files for privacy and security reasons, as they are an individual maintainer rather than a company.

Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: README.md:520-521
Timestamp: 2025-08-29T19:53:41.354Z
Learning: nerdCopter uses AGPL-3.0-or-later licensing for the bbl_parser project with a dual-licensing approach that includes a separate commercial license option.

Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: CONTRIBUTING.md:9-14
Timestamp: 2025-08-21T20:25:45.741Z
Learning: nerdCopter prefers to keep CLA language general using "project maintainer" rather than specifying a legal entity name, as they are an individual maintainer without an associated company.

Learnt from: nerdCopter
Repo: nerdCopter/bbl_parser PR: 2
File: LICENSE_COMMERCIAL:0-0
Timestamp: 2025-08-29T20:15:04.624Z
Learning: nerdCopter prefers clear positive indicators (✅) when describing fixes rather than using ❌ symbols which can be confusing when describing what was corrected in a positive context.

Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-13T15:51:00.137Z
Learning: Applies to src/main.rs : CLI (`src/main.rs`) should use library export functions (`export_to_csv`, `export_to_gpx`, `export_to_event`) with CLI-specific status messages

Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-13T15:51:00.137Z
Learning: Applies to src/lib.rs : Public API must expose: `parse_bbl_file()`, `parse_bbl_bytes()`, `BBLLog`, `ExportOptions`, `export_to_csv()`, `export_to_gpx()`, `export_to_event()`, conversion utilities, parser helpers

Learnt from: CR
Repo: nerdCopter/bbl_parser PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-13T15:51:00.137Z
Learning: Applies to {src/main.rs,src/conversion.rs,src/parser/{stream,helpers}.rs} : Comprehensive tests distributed across `src/main.rs`, `src/conversion.rs`, `src/parser/stream.rs`, and `src/parser/helpers.rs`