4.6 KiB
Slice 2.1 Implementation Log: GJC Tool Catalog Semantic Parity
Issue: #3323
Branch: lane/gjc-s21
Target: Bring read/edit/search/find tools to GJC semantics
Status: In Progress
Completed Work
Phase 1a: Read Tool Selector Parser ✅
Commit: 6b8bdb2c
Date: 2026-10-13
Components:
- ✅ New module:
rust/crates/runtime/src/line_range_selector.rs(343 LOC) - ✅ Line range selector parsing (
:L,:L-L+Nsyntax) - ✅ Special modes (
:raw,:conflicts) - ✅ Range merging logic for multi-range selectors
- ✅ 13 unit tests, all passing
Details:
- Supports formats:
:50,:50-200,:50+150,:5-16,960-973 - Automatically merges overlapping/adjacent ranges
- Type:
LineRangeSelectorenum with variants:Raw,Conflicts,Lines(Vec<LineRange>),None
In-Progress Work
Phase 1b: Integration into ReadFileOutput (🚧)
Target: Next commit
Scope:
- Update
ReadFileInputstruct inrust/crates/tools/src/lib.rsto include selector field - Update
read_file()function signature to accept selector parameter - Implement selector application in
read_file_in_workspace() - Update output format to include truncation footer
- Add tests for selector integration
Estimated LOC: 600-800
Complexity: Medium
Remaining Work (Planned)
Phase 1c: Truncation Footers & Metadata
Target: After 1b
Scope:
- Add
totalLinesfield to output - Add
totalBytesfield to output - Generate truncation footer with recovery hints
- Format footer:
[Showing lines X-Y of Z; re-read path:1-Z for full file] - Add tests for footer generation
Estimated LOC: 300-400
Phase 1d: Structural Summarization (Optional - Lower Priority)
Target: Later
Scope:
- Collapse function bodies to
..for code files - Preserve full lines for prose
- Add hash line anchors for structural boundaries
- Support code language detection
Estimated LOC: 400-600
Complexity: High
Batch 2: EDIT Tool Enhancements
Target: After Batch 1 complete
Scope:
- Add patch metadata to output (line numbers, context)
- Ensure exact match semantics
- Add comprehensive tests
Estimated LOC: 200-300
Batch 3: SEARCH/FIND Tools
Target: After Batches 1-2
Scope:
- Enhance grep with structured output
- Enhance find with metadata (file type, modified)
- Add filtering options
Estimated LOC: 400-500
PR Plan
PR 1: Read Selector Parser (Phase 1a) ✅
Status: Merged
Scope: Selector parsing logic
Files: line_range_selector.rs + lib.rs exports
Tests: 13 unit tests
PR 2: Read Selector Integration (Phase 1b-1c)
Status: Next
Scope: ReadFileInput/Output update + integration
Files: tools/lib.rs, file_ops.rs, tests
Size: ~1000 LOC
PR 3: EDIT Tool Enhancements (Batch 2)
Status: Planned
Scope: Output format enhancements
Size: ~200 LOC
PR 4: SEARCH/FIND Tools (Batch 3)
Status: Planned
Scope: Output format & filtering
Size: ~400 LOC
Testing Strategy
Each phase includes:
- Unit Tests: Core functions (parsing, selection, formatting)
- Integration Tests: End-to-end tool invocation
- Parity Tests: Compare outputs against GJC reference (manual)
Test Files
rust/crates/runtime/src/line_range_selector.rs:tests✅ (13 tests)rust/crates/runtime/src/file_ops.rs:tests(to be extended)rust/crates/tools/src/lib.rs:tests(to be extended)
Risk Assessment
| Risk | Mitigation | Priority |
|---|---|---|
| Large refactor breaks existing tests | Keep changes isolated, extend existing structs | High |
| GJC semantics unclear | Reference gajae-code/tools/read.ts directly | High |
| Performance regression | Benchmark file ops against baseline | Medium |
| Windows path handling | Use existing normalize_for_comparison logic | Medium |
References
- GJC Read Tool:
/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts - Gap Matrix:
docs/gjc-compat/gap-matrix.md - Semantics Doc:
docs/gjc-compat/tool-semantics-phase1.md - Current Implementation:
rust/crates/runtime/src/file_ops.rs:713 - Tool Input Schema:
rust/crates/tools/src/lib.rs:2884
Next Steps
- Immediate (this turn): Implement Phase 1b (ReadFileInput/Output integration)
- Short-term (next commit): Add Phase 1c (truncation footers)
- Medium-term: Batch 2 (EDIT tool) and Batch 3 (SEARCH/FIND)
- Verification: Manual parity testing against GJC reference
- Merge: Create focused PRs, merge when checks pass