Skip to content

Commit 6e6ffc1

Browse files
author
fer
committed
docs: add Phase 2 optimization roadmap
- Define 5 tasks for Phase 2 (12-17h estimated) - Task priorities: definitions.py split (high), performance (medium), docs (low) - Success criteria: <1000 lines/file, >85% coverage, 0 lint warnings - Update DOCUMENTATION_INDEX.md with Phase 2 reference - Ready to start optimization/phase-2 branch
1 parent a5db75a commit 6e6ffc1

File tree

2 files changed

+302
-0
lines changed

2 files changed

+302
-0
lines changed

‎DOCUMENTATION_INDEX.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ Generated from code + narrative docs:
8181
| **[TESTING.md](TESTING.md)** | Test conventions | Writing tests |
8282
| **[MIGRATION_GUIDE.md](MIGRATION_GUIDE.md)** | Modular architecture migration | Upgrading code |
8383
| **[SECURITY.md](SECURITY.md)** | Security policies | Reporting issues |
84+
| **[OPTIMIZATION_PHASE_2_ROADMAP.md](OPTIMIZATION_PHASE_2_ROADMAP.md)** | Phase 2 optimization plan | Active development |
8485

8586
### Specialized Topics
8687

‎OPTIMIZATION_PHASE_2_ROADMAP.md‎

Lines changed: 301 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,301 @@
1+
# TNFR Optimization Phase 2 Roadmap
2+
3+
**Status**: 🟢 ACTIVE
4+
**Started**: 2025-11-14
5+
**Phase 1**: ✅ COMPLETADO (5/5 tasks, 11.5h, commits 71ae4285c..a5db75af1)
6+
7+
---
8+
9+
## 🎯 Phase 2 Objectives
10+
11+
**Focus**: Code quality, performance optimization, and comprehensive documentation updates
12+
13+
**Duration Estimate**: 12-15 hours
14+
**Priority**: Medium-High
15+
**Success Criteria**:
16+
- All modules follow consistent patterns
17+
- Performance benchmarks established
18+
- Documentation fully aligned with code splits
19+
- Test coverage >85%
20+
21+
---
22+
23+
## 📋 Task List
24+
25+
### Task 1: Split Remaining Large Files (4-5h) 🔴 HIGH PRIORITY
26+
27+
**Objective**: Continue modularization of oversized files
28+
29+
**Targets**:
30+
1. **`src/tnfr/operators/definitions.py`** (~1,800 lines)
31+
- Split by operator: one file per operator
32+
- Create `definitions/` directory
33+
- Preserve `definitions.py` as facade
34+
- Operators: AL, EN, IL, OZ, UM, RA, SHA, VAL, NUL, THOL, ZHIR, NAV, REMESH
35+
36+
2. **`src/tnfr/validation/compatibility.py`** (~800 lines)
37+
- Split into: types, levels, matchers, utils
38+
- Estimated: 4 files + facade
39+
40+
3. **`src/tnfr/dynamics/step.py`** (~600 lines) - if needed
41+
- Split into: core, telemetry, observers
42+
- Estimated: 3 files + facade
43+
44+
**Deliverables**:
45+
- [ ] `scripts/split_definitions.py` automation script
46+
- [ ] 13+ operator files in `definitions/` directory
47+
- [ ] `definitions.py` facade with 100% backward compatibility
48+
- [ ] Comprehensive tests (100+ tests for definitions)
49+
- [ ] Commit: "refactor: split definitions.py into per-operator modules (Phase 2, Task 1)"
50+
51+
**Estimated Time**: 4-5 hours
52+
**Risk**: Medium (definitions.py is heavily imported)
53+
54+
---
55+
56+
### Task 2: Performance Benchmarking & Optimization (3-4h) 🟡 MEDIUM PRIORITY
57+
58+
**Objective**: Establish performance baselines and optimize hot paths
59+
60+
**Targets**:
61+
1. **Benchmark Suite Enhancement**
62+
- Add memory profiling to existing benchmarks
63+
- Create comparison baseline (pre-split vs post-split)
64+
- Focus areas: grammar validation, metrics computation, step()
65+
66+
2. **Optimization Opportunities**
67+
- Profile import times (after splits)
68+
- Identify hot loops in grammar_core.py
69+
- Cache expensive computations (phase verification, operator sets)
70+
- Consider lazy imports for heavy modules
71+
72+
3. **Performance Tests**
73+
- Add `tests/performance/test_grammar_performance.py` (if not exists)
74+
- Add `tests/performance/test_metrics_performance.py`
75+
- Establish regression thresholds
76+
77+
**Deliverables**:
78+
- [ ] Performance benchmark results (baseline.json)
79+
- [ ] Optimization patches (if >10% improvement found)
80+
- [ ] Performance test suite
81+
- [ ] Commit: "perf: establish performance baselines and optimize hot paths (Phase 2, Task 2)"
82+
83+
**Estimated Time**: 3-4 hours
84+
**Risk**: Low
85+
86+
---
87+
88+
### Task 3: Documentation Alignment (2-3h) 🟢 LOW PRIORITY
89+
90+
**Objective**: Update all documentation to reflect Phase 1 splits
91+
92+
**Targets**:
93+
1. **Update ARCHITECTURE.md**
94+
- Document new module structure (metrics, grammar)
95+
- Add architecture diagrams (Mermaid)
96+
- Explain facade pattern usage
97+
98+
2. **Update DOCUMENTATION_INDEX.md**
99+
- Add references to new modules
100+
- Update code navigation guides
101+
- Add split scripts to tools section
102+
103+
3. **Update API docs** (`docs/source/api/`)
104+
- Regenerate with Sphinx (if needed)
105+
- Ensure new modules appear correctly
106+
- Add migration notes for importers
107+
108+
4. **Update CONTRIBUTING.md**
109+
- Add guidance on modular structure
110+
- Explain when to create new modules vs extend existing
111+
- Document facade pattern for backward compatibility
112+
113+
**Deliverables**:
114+
- [ ] ARCHITECTURE.md updated with module diagrams
115+
- [ ] DOCUMENTATION_INDEX.md reflects all new files
116+
- [ ] API docs regenerated (if needed)
117+
- [ ] CONTRIBUTING.md with modular guidance
118+
- [ ] Commit: "docs: align documentation with Phase 1 modular architecture (Phase 2, Task 3)"
119+
120+
**Estimated Time**: 2-3 hours
121+
**Risk**: Low
122+
123+
---
124+
125+
### Task 4: Test Coverage Improvements (2-3h) 🟡 MEDIUM PRIORITY
126+
127+
**Objective**: Increase test coverage and fix known test failures
128+
129+
**Targets**:
130+
1. **Fix Known Failures**
131+
- `test_sha_grammar_validation.py`: 6 failing tests (SHA-specific logic)
132+
- `test_unit/dynamics/test_grammar.py`: 9 failing tests (fallback logic)
133+
- Investigate root causes, implement fixes or mark as known issues
134+
135+
2. **Coverage Gaps**
136+
- Add tests for new module boundaries (imports, exports)
137+
- Add integration tests for split modules working together
138+
- Focus on edge cases in grammar_application.py
139+
140+
3. **Property-Based Tests**
141+
- Install `hypothesis` in test-env
142+
- Enable `tests/property/test_grammar_invariants.py`
143+
- Add property tests for metrics modules
144+
145+
**Deliverables**:
146+
- [ ] SHA grammar tests fixed or documented
147+
- [ ] Dynamics grammar tests fixed or documented
148+
- [ ] Hypothesis installed, property tests enabled
149+
- [ ] Coverage report showing >85% for operators/
150+
- [ ] Commit: "test: fix known failures and improve coverage (Phase 2, Task 4)"
151+
152+
**Estimated Time**: 2-3 hours
153+
**Risk**: Medium (may uncover deeper issues)
154+
155+
---
156+
157+
### Task 5: Code Quality & Linting (1-2h) 🟢 LOW PRIORITY
158+
159+
**Objective**: Ensure consistent code style and remove lint warnings
160+
161+
**Targets**:
162+
1. **Lint Cleanup**
163+
- Address "imported but unused" warnings in new modules
164+
- Fix line length violations (79 char limit)
165+
- Remove trailing whitespace
166+
- Add missing docstrings where needed
167+
168+
2. **Type Hints**
169+
- Add comprehensive type hints to new modules
170+
- Run `mypy` on operators/ directory
171+
- Fix type inconsistencies
172+
173+
3. **Code Formatting**
174+
- Run `black` on all new modules
175+
- Ensure consistent import ordering (isort)
176+
- Verify docstring format (Google style)
177+
178+
**Deliverables**:
179+
- [ ] Zero lint warnings in new modules
180+
- [ ] Type hints complete (mypy passing)
181+
- [ ] Code formatted (black, isort)
182+
- [ ] Commit: "style: clean up linting and improve type hints (Phase 2, Task 5)"
183+
184+
**Estimated Time**: 1-2 hours
185+
**Risk**: Low
186+
187+
---
188+
189+
## 📊 Phase 2 Metrics
190+
191+
### Success Criteria
192+
193+
| Metric | Target | Current (Phase 1 End) |
194+
|--------|--------|------------------------|
195+
| Module count | 280-290 | 259 |
196+
| Largest file | <1,000 lines | grammar_core.py (882) ✅ |
197+
| Test coverage (operators/) | >85% | ~75% (est.) |
198+
| Performance (vs baseline) | ±5% | TBD |
199+
| Lint warnings | 0 | ~50 (est.) |
200+
| Documentation completeness | 100% | ~90% |
201+
202+
### Deliverables Checklist
203+
204+
- [ ] **Task 1**: definitions.py split complete
205+
- [ ] **Task 2**: Performance baselines established
206+
- [ ] **Task 3**: Documentation fully aligned
207+
- [ ] **Task 4**: Test coverage >85%
208+
- [ ] **Task 5**: Code quality perfect
209+
210+
**Total Estimated Time**: 12-17 hours
211+
**Commits Expected**: 5 (one per task)
212+
213+
---
214+
215+
## 🚀 Execution Strategy
216+
217+
### Order of Operations
218+
219+
1. **Start with Task 1** (definitions.py split) - Highest impact, foundational
220+
2. **Then Task 4** (test coverage) - Validate split work, fix failures
221+
3. **Then Task 2** (performance) - Measure impact of splits
222+
4. **Then Task 5** (code quality) - Polish before documentation
223+
5. **Finally Task 3** (documentation) - Reflect final state
224+
225+
### Risk Mitigation
226+
227+
**Task 1 (definitions.py)**:
228+
- Create backup first (like grammar.py)
229+
- Use automation script (like split_grammar.py)
230+
- Test extensively before commit
231+
- Expect 6-8 import fix iterations
232+
233+
**Task 4 (test fixes)**:
234+
- Document "won't fix" issues clearly
235+
- Separate quick fixes from research-needed
236+
- Don't block Phase 2 on complex failures
237+
238+
### Branch Strategy
239+
240+
Continue on `main` (Phase 1 merged) OR create `optimization/phase-2` branch if preferred for safety.
241+
242+
**Recommendation**: Use `optimization/phase-2` branch, merge when complete.
243+
244+
---
245+
246+
## 📈 Expected Outcomes
247+
248+
After Phase 2 completion:
249+
250+
1. **Modularity**: All large files (<1,000 lines each)
251+
2. **Performance**: Baseline established, optimizations applied
252+
3. **Documentation**: 100% aligned with code structure
253+
4. **Tests**: >85% coverage, known issues documented
254+
5. **Quality**: Zero lint warnings, complete type hints
255+
256+
**Repository Health**: 100/100 maintained throughout
257+
**Backward Compatibility**: 100% preserved
258+
**TNFR Invariants**: All 10 preserved
259+
260+
---
261+
262+
## 🔄 Future Phases (Preview)
263+
264+
**Phase 3** (Potential, ~10h):
265+
- Enhanced error messages
266+
- Interactive tools (CLI validators)
267+
- Example gallery expansion
268+
- Tutorial improvements
269+
270+
**Phase 4** (Potential, ~8h):
271+
- CI/CD pipeline enhancements
272+
- Release automation
273+
- Performance regression tests
274+
- Integration with external tools
275+
276+
---
277+
278+
## 📝 Notes
279+
280+
**Phase 1 Accomplishments** (Reference):
281+
- ✅ 70+ new tests added
282+
- ✅ 13 new modules created (5 metrics + 8 grammar)
283+
- ✅ 2 large files split (metrics.py, grammar.py)
284+
- ✅ Dependabot configured
285+
- ✅ 5 commits, 11.5h total
286+
- ✅ Health 100/100 maintained
287+
288+
**Phase 2 Philosophy**:
289+
- Continue incremental, validated changes
290+
- Prioritize backward compatibility
291+
- Document everything
292+
- Test exhaustively
293+
- Maintain TNFR physics fidelity
294+
295+
---
296+
297+
**Last Updated**: 2025-11-14
298+
**Status**: 🟢 READY TO START
299+
**Approver**: @fermga
300+
301+
**Next Action**: Create `optimization/phase-2` branch and start Task 1 (definitions.py split)

0 commit comments

Comments
 (0)