Design & Implementation Plan: Fix SearchResultDoc Compilation Errors in Integration Tests

1. Summary of Target Behavior

After implementation, the integration test files will compile successfully without errors. Specifically:

crates/terraphim_agent/tests/kg_ranking_integration_test.rs will compile without the SearchResultDoc type errors
crates/terraphim_agent/tests/cross_mode_consistency_test.rs will compile and pass (already works)
All 3 test files in the test suite will execute successfully
No dead code warnings from unused variables
Minimal changes to preserve the intent of disabled CLI mode functionality

2. Key Invariants and Acceptance Criteria

Invariants

Compilation Success: All test files must compile without errors
Test Execution: All tests must run and pass (or be appropriately skipped)
No Regressions: Existing working tests must continue to work
Code Hygiene: No dead code warnings or unused variable warnings
Intent Preservation: The disabled CLI mode code paths remain disabled but documented

Acceptance Criteria

| Criterion | Test Method | |-----------|-------------| | kg_ranking_integration_test.rs compiles | cargo check --test kg_ranking_integration_test returns success | | cross_mode_consistency_test.rs compiles and runs | cargo test --test cross_mode_consistency_test passes | | repl_integration_tests.rs compiles and runs | cargo test --test repl_integration_tests passes | | No compiler warnings | cargo check --tests produces no warnings for these files | | All tests pass | cargo test -p terraphim_agent shows all tests passing |

3. High-Level Design and Boundaries

Solution Approach

The SearchResultDoc type is used only in disabled CLI mode code paths. The simplest fix is to comment out these placeholder lines rather than defining a new unused type.

Boundaries

Inside boundary: Test files in crates/terraphim_agent/tests/
Outside boundary: No changes to production code, library APIs, or other crates
Preservation boundary: Disabled CLI functionality remains commented (not removed) to preserve intent for future implementation

Change Strategy

Comment out lines 454 and 604 in kg_ranking_integration_test.rs that reference SearchResultDoc
These lines initialize placeholder variables that are never used (CLI mode disabled)
Add explanatory comments indicating these are CLI mode placeholders

Avoided Approaches

Defining SearchResultDoc type: Would add unused code and maintenance burden
Removing CLI mode code entirely: Would lose documentation of intended functionality
Refactoring to use NormalizedResult: Unnecessary complexity for disabled code paths

4. File/Module-Level Change Plan

| File | Action | Before | After | Dependencies | |------|--------|--------|-------|--------------| | crates/terraphim_agent/tests/kg_ranking_integration_test.rs | Modify | Lines 454-455: let cli_docs: Vec<SearchResultDoc> = vec![]; let cli_ranks: Vec<f64> = vec![]; | Commented out with explanatory note | None - dead code removal | | crates/terraphim_agent/tests/kg_ranking_integration_test.rs | Modify | Lines 604-605: let cli_docs: Vec<SearchResultDoc> = vec![]; let cli_ranks: Vec<f64> = vec![]; | Commented out with explanatory note | None - dead code removal | | crates/terraphim_agent/tests/cross_mode_consistency_test.rs | Verify | Unknown state | Compile and verify tests pass | Depends on fix in other files |

Responsibility Changes

kg_ranking_integration_test.rs: Remove references to undefined type in dead code paths
cross_mode_consistency_test.rs: Verify no similar issues exist (uses NormalizedResult correctly)
repl_integration_tests.rs: Verify no similar issues exist (already compiles successfully)

5. Step-by-Step Implementation Sequence

Step 1: Comment Out SearchResultDoc References in First Location

File: crates/terraphim_agent/tests/kg_ranking_integration_test.rs (lines 454-455) Purpose: Remove undefined type reference Deployable: Yes - no functional change, only removes dead code Action:

// CLI mode comparison - disabled (see issue #XXX)
// let cli_docs: Vec<SearchResultDoc> = vec![];
// let cli_ranks: Vec<f64> = vec![];

Step 2: Comment Out SearchResultDoc References in Second Location

File: crates/terraphim_agent/tests/kg_ranking_integration_test.rs (lines 604-605) Purpose: Remove second undefined type reference Deployable: Yes - no functional change Action:

// CLI mode disabled - server mode only testing
// let cli_docs: Vec<SearchResultDoc> = vec![];
// let cli_ranks: Vec<f64> = vec![];

Step 3: Verify Compilation

Command: cargo check -p terraphim_agent --test kg_ranking_integration_test Purpose: Confirm compilation succeeds Deployable: N/A (verification step)

Step 4: Run All Tests

Command: cargo test -p terraphim_agent --test kg_ranking_integration_test Purpose: Verify tests execute successfully Deployable: N/A (verification step)

Step 5: Cross-Check Other Test Files

Commands:

cargo test -p terraphim_agent --test cross_mode_consistency_test
cargo test -p terraphim_agent --test repl_integration_tests Purpose: Ensure no regressions in other tests Deployable: N/A (verification step)

Step 6: Final Verification

Command: cargo test -p terraphim_agent Purpose: Full test suite passes Deployable: Yes - all tests green

6. Testing & Verification Strategy

| Acceptance Criteria | Test Type | Test Location | Command | |---------------------|-----------|---------------|---------| | No compilation errors | Static Analysis | kg_ranking_integration_test.rs | cargo check --test kg_ranking_integration_test | | Tests execute | Integration Test | kg_ranking_integration_test.rs | cargo test --test kg_ranking_integration_test | | No regressions | Regression Test | All test files | cargo test -p terraphim_agent | | No warnings | Lint Check | All test files | cargo check --tests -p terraphim_agent |

Test Execution Plan

Pre-fix: Document current failure state (screenshot error messages)
Post-fix Step 1: Verify compilation succeeds
Post-fix Step 2: Run tests and confirm pass count
Post-fix Step 3: Verify no compiler warnings
Final: All tests in terraphim_agent crate pass

7. Risk & Complexity Review

| Risk | Mitigation | Residual Risk | |------|------------|---------------| | Commenting out wrong lines | Careful line number verification | Low - easy to revert | | Breaking test logic | Only removing unused variables | Low - no functional impact | | Compiler warnings from commented code | Rust allows commented code without warnings | None | | Other similar issues in test files | Verification step covers all test files | Low - already checked repl tests work | | Test expectations may reference cli_docs/cli_ranks | Search for usage before commenting | Low - grep shows no usage |

Complexity Assessment

Scope: Very narrow - only 4 lines in 1 file
Risk Level: Very Low - dead code removal only
Reversibility: Fully reversible (just uncomment)
Blast Radius: Zero - no production code affected

8. Open Questions / Decisions for Human Review

Should we add a TODO/FIXME comment referencing an issue number for future CLI mode implementation?
- Context: The disabled CLI functionality may be re-enabled in the future
- Options: (a) Add TODO comment with issue reference, (b) Keep simple comment as shown above
Should we completely remove the CLI mode code instead of commenting it out?
- Context: The CLI mode code has been disabled for some time
- Options: (a) Comment out (preserves intent), (b) Delete entirely (cleaner code)
Is there a specific GitHub issue tracking the CLI mode functionality that we should reference?
- Context: Would help future developers understand why CLI mode is disabled
- Options: (a) Add issue number if known, (b) Leave as-is if no issue exists

Recommendation: Proceed with simple comments (no TODO/issue reference) as this is minimal-impact cleanup of dead code. The disabled CLI functionality is already well-documented in the test file headers.