From 7569cc970d0d99b0f30a5a88d478c1b8f711118b Mon Sep 17 00:00:00 2001 From: Ed_ Date: Wed, 17 Jun 2026 15:50:45 -0400 Subject: [PATCH] docs(track): result_migration_review_pass decisions for src/rag_engine.py INTERNAL_RETHROW (2 PATTERN_1/2 + 2 compliant + 0 migration-target; noted audit script bug) --- .../RESULT_MIGRATION_REVIEW_PASS_20260617.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md b/docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md index fe64ea41..d9d6697f 100644 --- a/docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md +++ b/docs/reports/RESULT_MIGRATION_REVIEW_PASS_20260617.md @@ -153,7 +153,20 @@ Other audit findings (unchanged by this review pass): ### 2.8 `src/rag_engine.py` — INTERNAL_RETHROW sites (4, baseline) -*(filled in Task 3.2)* +| Line | Context | Snippet | Decision | Pattern / Rationale | +|---|---|---|---|---| +| 29 | `_get_sentence_transformers` (lazy import) | `except ModuleNotFoundError as e:` (start of except) | **PATTERN_1** (composite) | The except body contains both a `raise ImportError(LOCAL_RAG_INSTALL_HINT) from e` (PATTERN_1: catch + convert + raise with better message) and a bare `raise` (PATTERN_2: re-raise original). The except itself is the boundary | +| 36 | `_get_sentence_transformers` (lazy import) | `raise e` after `sys.stderr.write(...)` | **PATTERN_2** | Catch + log + re-raise: writes to stderr, then re-raises the original exception. The log is for observability; the re-raise preserves the traceback for the caller | +| 57 | `BaseEmbeddingProvider.embed` (abstract method) | `raise NotImplementedError()` | **compliant** | Abstract method pattern: the base class raises `NotImplementedError` to signal subclasses must implement. The audit script's `_classify_raise` heuristic misses this (the function is not `__init__` and `NotImplementedError` doesn't match the `AssertionError, ValueError, or assert` check) | +| 75 | `GeminiEmbeddingProvider.embed` (validation) | `raise ImportError("google-genai is not installed")` after `if google_module is None` | **compliant** | Validation raise: if a required dependency is missing, raise with an actionable message. This is the "explicit precondition check" pattern (per styleguide's "Constructors that fail with programmer errors" guidance) | + +**Subtotals:** 2 PATTERN_1/2 + 2 compliant + 0 migration-target. + +**Note (audit script bug, OUT OF SCOPE for this review pass):** The audit script's `visit_Try` method has a bug — it iterates over `node.handlers` for adding findings but then visits children of only the LAST handler's body. This causes it to miss `raise` statements in the first except handler. The `raise ImportError(LOCAL_RAG_INSTALL_HINT) from e` at L31 (in the first `except ModuleNotFoundError`) is a legitimate PATTERN_1 site that the audit misses. Document for future audit script fix. + +**New heuristic candidates:** +- `raise NotImplementedError()` as the entire function body → `INTERNAL_PROGRAMMER_RAISE` (abstract method pattern; the current heuristic checks `__init__` but should also check the function is the entire body) +- `if is None: raise ImportError(...)` or similar validation raise → `INTERNAL_PROGRAMMER_RAISE` (precondition check pattern) ---