From f004b58e4baced5ba1f2440ff51b299c1a9a2533 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Wed, 17 Jun 2026 15:05:26 -0400 Subject: [PATCH] docs(track): result_migration_review_pass decisions for src/gui_2.py UNCLEAR (12 compliant + 1 migration-target) --- .../RESULT_MIGRATION_REVIEW_PASS_20260617.md | 153 ++++++++++++++++++ 1 file changed, 153 insertions(+) create mode 100644 docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md diff --git a/docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md b/docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md new file mode 100644 index 00000000..5d23b5a6 --- /dev/null +++ b/docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md @@ -0,0 +1,153 @@ +# Result Migration Sub-Track 1: Review Pass Report + +**Track:** `result_migration_review_pass_20260617` +**Umbrella:** [`result_migration_20260616`](../../tracks/result_migration_20260616/spec.md) +**Type:** audit + documentation (informational; no production code change) +**Status:** active +**Date:** 2026-06-17 + +--- + +## 0. Executive Summary + +This report captures the per-site decisions for the **43 ambiguous exception-handling sites** identified by `scripts/audit_exception_handling.py --json` on 2026-06-17: + +- **24 UNCLEAR** sites (the script cannot classify from AST alone) +- **19 INTERNAL_RETHROW** sites (`try/except + raise`; needs the 3 legitimate pattern checks) + +Each site was reviewed by reading the snippet + 2-3 lines of context. The decisions flow into the umbrella's sub-tracks 2-4 as their starting migration scope. + +--- + +## 1. Pre-Review Audit Snapshot (2026-06-17, base commit `b6caca40`) + +| Bucket | Count | Description | +|---|---|---| +| `UNCLEAR` | 24 | Script could not classify; needs human review | +| `INTERNAL_RETHROW` | 19 | `try/except + raise`; needs 3-pattern check | +| **Total review scope** | **43** | 11 files affected | + +Other audit findings (unchanged by this review pass): +- 211 violations (broad catch, silent swallow, Optional[T] return) — out of scope here +- 80 compliant sites — out of scope here +- 25 INTERNAL_PROGRAMMER_RAISE (raise in __init__ / assert) — compliant; out of scope + +--- + +## 2. Per-Site Decision Table + +### 2.1 `src/gui_2.py` — UNCLEAR sites (13) + +| Line | Context | Snippet | Decision | Pattern / Rationale | +|---|---|---|---|---| +| 65 | `_resolve` (deferred importer) | `except AttributeError: ... _FiledialogStub()` | **compliant** | Graceful degradation for missing optional modules (filedialog stub) | +| 69 | `_resolve` (deferred importer) | `except (ImportError, ModuleNotFoundError): _FiledialogStub()` | **compliant** | Graceful degradation for missing optional modules (filedialog stub) | +| 684 | `run` (ImGui main loop) | `except RuntimeError as _immapp_exc: ... log + keep alive` | **compliant** | Defer-not-catch for native bundle crashes (per workflow.md); logs to `_gui_degraded_reason` | +| 806 | `_get_active_capabilities` | `except KeyError: caps = VendorCapabilities(... notes="unregistered")` | **compliant** | Lookup-miss-with-default for `get_capabilities(provider, model)` | +| 1349 | `_populate_auto_slices` | `except Exception: return` | **migration-target** | Broad `except Exception` + silent return. Should narrow to `(OSError, UnicodeDecodeError)` or return `Result`. **Sub-track 4 (gui_2)** | +| 2401 | `render_rag_panel` (vector store provider combo) | `except (ValueError, AttributeError): idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom | +| 2411 | `render_rag_panel` (embedding provider combo) | `except (ValueError, AttributeError): idx_e = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom | +| 2533 | `render_agent_tools_panel` (tool preset combo) | `except ValueError: idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom | +| 2561 | `render_agent_tools_panel` (filter category combo) | `except ValueError: f_idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom | +| 2759 | `render_persona_selector_panel` (load persona context preset) | `except KeyError as e: app.ai_status = f"persona context preset missing: {e}"` | **compliant** | Lookup-miss-with-user-feedback; defensive but user-visible | +| 4106 | `render_context_files_table` (view mode combo) | `except ValueError: current_idx = 1; f_item.view_mode = "summary"` | **compliant** | `list.index` miss with default + state correction | +| 4159 | `render_context_presets` (context preset combo) | `except ValueError: idx = 0` | **compliant** | `list.index` miss with default; standard Python combo-box idiom | +| 6830 | `render_tier_stream_panel` (ImGui child end guard) | `except (TypeError, AttributeError): imgui.end_child()` | **compliant** | ImGui scope cleanup guard; ensures `end_child()` is always called | + +**Subtotals:** 12 compliant + 1 migration-target. + +**New heuristics identified for the audit script (added in Task 4.1):** +1. `list.index` with `ValueError` fallback to a default index → `INTERNAL_COMPLIANT` +2. `dict.get` / `KeyError` lookup with default value construction → `INTERNAL_COMPLIANT` +3. Narrow `except (RuntimeError, OSError, AttributeError, ImportError)` + `imgui.end_*` or stub construction → `INTERNAL_COMPLIANT` (defer-not-catch for ImGui) +4. Narrow `except (ImportError, ModuleNotFoundError, AttributeError)` + fallback attribute/stub → `INTERNAL_COMPLIANT` (graceful degradation) + +--- + +### 2.2 `src/mcp_client.py` — UNCLEAR sites (4, baseline) + +*(filled in Task 2.2)* + +--- + +### 2.3 `src/ai_client.py` — UNCLEAR sites (2, baseline) + +*(filled in Task 2.3)* + +--- + +### 2.4 `src/app_controller.py` — UNCLEAR sites (2) + +*(filled in Task 2.4)* + +--- + +### 2.5 `src/models.py` — UNCLEAR sites (2) + +*(filled in Task 2.5)* + +--- + +### 2.6 `src/multi_agent_conductor.py` — UNCLEAR sites (1) + +*(filled in Task 2.6)* + +--- + +### 2.7 `src/ai_client.py` — INTERNAL_RETHROW sites (6, baseline) + +*(filled in Task 3.1)* + +--- + +### 2.8 `src/rag_engine.py` — INTERNAL_RETHROW sites (4, baseline) + +*(filled in Task 3.2)* + +--- + +### 2.9 `src/app_controller.py` — INTERNAL_RETHROW sites (3) + +*(filled in Task 3.3)* + +--- + +### 2.10 `src/gui_2.py` — INTERNAL_RETHROW sites (2) + +*(filled in Task 3.4)* + +--- + +### 2.11 `src/api_hooks.py` — INTERNAL_RETHROW sites (2) + +*(filled in Task 3.5)* + +--- + +### 2.12 `src/models.py` — INTERNAL_RETHROW site (1) + +*(filled in Task 3.6)* + +--- + +### 2.13 `src/warmup.py` — INTERNAL_RETHROW site (1) + +*(filled in Task 3.7)* + +--- + +## 3. Post-Review Migration Scope + +*(filled in Task 5.1)* + +--- + +## 4. Audit Script Heuristic Updates + +*(filled in Task 4.1)* + +--- + +## 5. Verification + +*(filled in Phase 6)*