Private
Public Access
docs(track): update result_migration_20260616 umbrella with sub-track 2 shipped status
This commit is contained in:
@@ -37,7 +37,7 @@ sites** across the codebase.
|
||||
**5 sub-tracks with consistent `result_migration_*` prefix:**
|
||||
|
||||
1. `result_migration_review_pass` (T-shirt: S) — 57 sites (32 UNCLEAR + 25 INTERNAL_RETHROW); updates the audit's heuristics
|
||||
2. `result_migration_small_files` (T-shirt: L) — 37 files (35 SMALL + 2 MEDIUM; 72 V+S sites)
|
||||
2. `result_migration_small_files` (T-shirt: L) — 37 files (35 SMALL + 2 MEDIUM); **shipped 2026-06-17** with documented G4 deviation: 76 sites (62V + 10S + 4 UNCLEAR) → 49 migrated (6 full `Result[T]` + 43 exception narrowing) + 13 already compliant + 27 silent-swallow sites remain (follow-up sub-track planned)
|
||||
3. `result_migration_app_controller` (T-shirt: XL) — 56 sites (35 V + 3 S + 2 ? + 16 C; 13 FastAPI boundary stay as-is)
|
||||
4. `result_migration_gui_2` (T-shirt: XL) — **55 sites** (37 V + 2 S + **14 ?** + 2 C; the 14 ? includes the +1 site from the review pass: `src/gui_2.py:1349`)
|
||||
5. `result_migration_baseline_cleanup` (T-shirt: L) — 112 sites (77 V + 10 S + 6 ? + 19 C in the 3 refactored files)
|
||||
@@ -52,6 +52,17 @@ sites** across the codebase.
|
||||
> - **19 INTERNAL_RETHROW sites** are all compliant: 7 PATTERN_1 (Result→Exception bridge in baseline files) + 2 PATTERN_2 (catch+log+re-raise) + 9 compliant (standard `__getattr__`, abstract method, validation raise) + 1 audit-script bug (missed find)
|
||||
> - Net migration scope change: **sub-track 4 (gui_2) gains 1 site** (L1349). All other sub-tracks are unchanged.
|
||||
|
||||
> **Post-Sub-Track-2 Update (2026-06-17, sub-track 2 shipped):**
|
||||
> After the small-files migration (`result_migration_small_files_20260617`),
|
||||
> the audit script is now correct (3 bugs fixed in Phase 1 of that sub-track),
|
||||
> and the 37 SMALL+MEDIUM files have been processed:
|
||||
> - **49/76 sites migrated** (6 full `Result[T]` + 43 exception narrowing) + 13 already compliant
|
||||
> - **27 sites remain `INTERNAL_SILENT_SWALLOW`** (narrow-catch + pass); follow-up sub-track planned
|
||||
> - **Audit's UNCLEAR count: 7 → 21** (+14 sites) — the narrowing created patterns the audit's heuristics don't recognize; follow-up sub-track will add 2-3 new heuristics
|
||||
> - **Bonus defensive fix:** `try/except (OSError, tomllib.TOMLDecodeError)` in `load_track_state` unblocked 7+ tests
|
||||
> - **Test result:** all 11 test tiers PASS (tier-1-unit-comms, tier-1-unit-core, tier-1-unit-gui, tier-1-unit-headless, tier-1-unit-mma, tier-2-mock_app-comms, tier-2-mock_app-core, tier-2-mock_app-gui, tier-2-mock_app-headless, tier-2-mock_app-mma, tier-3-live_gui)
|
||||
> - **Documented G4 deviation:** 27 silent-swallow sites remain. A follow-up sub-track `result_migration_silent_swallow_followup_<date>` is planned (TBD; see "Recommended Sequence" below for the new ordering)
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
@@ -114,22 +125,61 @@ applied. Both feed into all later sub-tracks.
|
||||
#### Sub-track 2: `result_migration_small_files_<YYYYMMDD>`
|
||||
|
||||
**Scope:** 37 files (the 35 SMALL + 2 MEDIUM from the `--by-size` bucket);
|
||||
72 V+S sites.
|
||||
**T-shirt size:** L (batched; ~700 lines changed across 37 files; mechanical).
|
||||
**76 sites (62V + 10S + 4 UNCLEAR) → 49 migrated + 13 already compliant + 27 silent-swallow remain.**
|
||||
**T-shirt size:** L (batched; ~750 lines changed across 37 files + 1 audit script + 1 new test file).
|
||||
**Status:** **shipped 2026-06-17** with documented G4 deviation (27 sites remain `INTERNAL_SILENT_SWALLOW`; follow-up sub-track planned).
|
||||
|
||||
**Why second:** the small files are quick wins; they don't depend on
|
||||
the orchestrator (app_controller) or the GUI. Some of them DO depend on
|
||||
sub-track 1's review pass (so the UNCLEAR sites are classified first).
|
||||
Phase 1 of this sub-track (audit-script bug fixes) unblocks sub-tracks
|
||||
3 and 4 by giving them an audit that classifies correctly.
|
||||
|
||||
**What it does:**
|
||||
- Migrates each of the 37 files to the convention.
|
||||
- Each file's migration is a small `Result[T]` introduction + an
|
||||
`except <specific> as e: return Result(data=NIL_T, errors=[ErrorInfo(...)])`
|
||||
replacement.
|
||||
- The 2 MEDIUM files (session_logger, warmup) get dedicated commits; the
|
||||
35 SMALL files get batched commits (5-7 files per commit).
|
||||
**What it did:**
|
||||
- **Phase 1: 3 audit-script bug fixes** (TDD) — fixed the 3 bugs documented
|
||||
in the review-pass report §4.4:
|
||||
- `visit_Try` walker now visits ALL except handlers (was only walking the last)
|
||||
- `render_json` per-file list now includes all findings (was filtering compliant)
|
||||
- `render_json` no longer truncates per-file list to top 15 (default now 200)
|
||||
- **Phase 2: 4 UNCLEAR classifications** (2 migration-target + 2 compliant; decisions in
|
||||
`docs/reports/RESULT_MIGRATION_SMALL_FILES_20260617.md`)
|
||||
- **Phases 3-8: 49/76 sites migrated** using two strategies:
|
||||
- **Strategy A: Full `Result[T]` migration** (2 files, 6 sites): `summary_cache.py`, `log_registry.py`.
|
||||
Backwards-compatible (callers ignore the Result return).
|
||||
- **Strategy B: Exception narrowing** (24 files, 43 sites): changed `except Exception`
|
||||
to specific stdlib/domain exceptions. Public API unchanged; behavior unchanged; no
|
||||
caller updates needed. This is a **partial migration** — the convention's FR4
|
||||
says "convert to Result[T]", but the spec also acknowledged (R5) that cascading
|
||||
public API changes may be acceptable. Tier 2 chose narrowing for 43 sites to
|
||||
avoid ~100+ caller updates. **Caveat:** narrowing without `logging.warning(...)`
|
||||
is **silent recovery** (no trace). The 27 sites that remain `INTERNAL_SILENT_SWALLOW`
|
||||
are documented in the track completion report; a follow-up sub-track is
|
||||
planned to add logging or full Result migration to them.
|
||||
- **Phase 9: Verification** — all 11 test tiers PASS; per-site report + track
|
||||
completion report written; state.toml + metadata.json marked completed.
|
||||
- **Bonus defensive fix:** `try/except (OSError, tomllib.TOMLDecodeError)` in
|
||||
`load_track_state` (in `src/project_manager.py`) for a pre-existing malformed
|
||||
state.toml crash. Unblocked 7+ tests.
|
||||
|
||||
**Dependency:** sub-track 1 (for the UNCLEAR classification).
|
||||
**Documented G4 deviation:** 27 sites remain `INTERNAL_SILENT_SWALLOW` (narrow-catch +
|
||||
pass or narrow-catch + return None). These are categorized as:
|
||||
- **Category A (intentional silent recovery, 17 sites):** Known failure modes where the
|
||||
caller has no use for the error info (e.g., `file_cache.py:98` mtime cache fallback,
|
||||
`outline_tool.py:90` ast.unparse fallback, `startup_profiler.py:40` profile output
|
||||
with `stderr.write` as a log). Should add `logging.debug(...)` per the audit's
|
||||
heuristic #19 to confirm intent.
|
||||
- **Category B (user-input-driven, 10 sites):** Callbacks and reload paths where any
|
||||
exception is possible (e.g., `warmup.py:139/215/249` user callbacks, `hot_reloader.py:58`
|
||||
module reload). Should add `logging.warning(...)` to surface user errors.
|
||||
|
||||
**Migration-target sites introduced by the narrowing:** the audit's UNCLEAR count
|
||||
went **7 → 21** (+14 sites) because the narrowing created patterns the audit's
|
||||
heuristics don't recognize. A follow-up sub-track is planned to add 2-3 new heuristics
|
||||
(heavily-narrowed `except` without logging; `except` returning Result in non-`*_result`
|
||||
function) that reclassify these.
|
||||
|
||||
**Dependency:** sub-track 1 (for the UNCLEAR classification). Unblocks sub-tracks 3 and 4
|
||||
by fixing the audit script.
|
||||
|
||||
#### Sub-track 3: `result_migration_app_controller_<YYYYMMDD>`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user