fix(documents): log TOC analyzer failures instead of swallowing them silently (edgartools-hk9w)

The analyzer degraded silently on internal errors — blanket 'except Exception: pass'
in _analyze_generic_toc, _extract_preceding_item_label, _infer_part_from_row_context,
_anchor_matches_heading, and the module-level _find_toc_table_start, plus an
unlogged agent-parser fallthrough. When an agent parser threw or found nothing,
the analyzer dropped to the generic fallback (or returned {}) with no signal —
exactly the blindness that let the GS/Citi section bugs hide.

Every catch now emits logger.debug(..., exc_info=True) with context, matching the
already-logged agent parsers (Workiva/DFIN/Novaworks/Toppan, body-header scan). The
agent fallthrough logs which parser returned nothing before degrading to the generic
scan. The one remaining narrow catch (except (ValueError, AttributeError): continue
in the per-anchor loop) stays as-is — already typed, and per-anchor logging is noise.

Tests: test_agent_fallthrough_logs (caplog asserts the fallthrough log names the
parser) and test_no_blanket_silent_except (guard against any 'except Exception: pass'
regressing). test_toc_agents 44 passed; broader TOC/section/corpus run 85 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dgunning

edgar/documents/utils/toc_analyzer.py

@@ -94,6 +94,11 @@ def analyze_toc_structure(self, html_content: str, agent: Optional[str] = None,
 
         # Generic fallback for unknown agents or when agent-specific parser returns empty
         if not result:
+            if agent:
+                # The agent parser was tried and found nothing — make the
+                # degradation to the generic scan observable (edgartools-hk9w).
+                logger.debug("Agent parser %r returned no sections; "
+                             "falling back to generic TOC scan", agent)
             result = self._analyze_generic_toc(html_content, tree=tree)
 
         # Body-header fallback: some filers (Goldman Sachs, Citi — large bank
@@ -212,8 +217,9 @@ def _analyze_generic_toc(self, html_content: str, tree=None) -> Dict[str, str]:
             section_mapping = self._build_section_mapping(toc_sections, tree=tree)
 
         except Exception:
-            # Return empty mapping on error - fallback to other methods
-            pass
+            # Degrade to other strategies, but record why the generic scan failed
+            # so the silent-fallback path stays diagnosable (edgartools-hk9w).
+            logger.debug("Generic TOC parser failed", exc_info=True)
 
         return section_mapping
 
@@ -951,7 +957,7 @@ def _extract_preceding_item_label(self, link_element) -> str:
                         return part_match.group(1)
 
         except Exception:
-            pass
+            logger.debug("Preceding-item-label extraction failed", exc_info=True)
 
         return ''
 
@@ -1015,6 +1021,7 @@ def _infer_part_from_row_context(self, link_element) -> Optional[str]:
                 prev = prev.getprevious()
 
         except Exception:
+            logger.debug("Part inference from row context failed", exc_info=True)
             return None
 
         return None
@@ -1332,7 +1339,7 @@ def _anchor_matches_heading(self, tree, anchor_id: str, expected_name: str) -> b
                     if item_pattern in el_text:
                         return True
         except Exception:
-            pass
+            logger.debug("Anchor/heading match check failed", exc_info=True)
 
         return False
 
@@ -1475,6 +1482,6 @@ def _find_toc_table_start(html_content: str) -> int:
                         return pos
 
     except Exception:
-        pass
+        logger.debug("TOC table-start scan failed", exc_info=True)
 
     return -1

tests/test_toc_agents.py

@@ -678,3 +678,35 @@ def test_cat_item_1d_is_canonical_and_correct(self):
         canon = TOCAnalyzer._CANONICAL_ITEM_KEY
         assert all(canon.match(k) for k in secs.keys()), \
             f"non-canonical: {[k for k in secs if not canon.match(k)]}"
+
+
+class TestSilentFailureObservability:
+    """The TOC analyzer must not swallow failures silently (edgartools-hk9w):
+    the agent-parser fallthrough and internal errors emit debug logs so the
+    degradation path is diagnosable."""
+
+    def test_agent_fallthrough_logs(self, caplog):
+        """When a named agent parser finds nothing and we degrade to the generic
+        scan, a debug log identifies which parser fell through."""
+        import logging
+        analyzer = TOCAnalyzer(form='10-K')
+        # HTML with no Workiva TOC structure -> _analyze_workiva_toc returns {} ->
+        # fallthrough to generic.
+        html = "<html><body><p>No table of contents here.</p></body></html>"
+        with caplog.at_level(logging.DEBUG, logger='edgar.documents.utils.toc_analyzer'):
+            analyzer.analyze_toc_structure(html, agent='Workiva')
+        assert any('Workiva' in r.message and 'generic' in r.message.lower()
+                   for r in caplog.records), \
+            f"no fallthrough log; records={[r.message for r in caplog.records]}"
+
+    def test_no_blanket_silent_except(self):
+        """Guard: no 'except Exception:' in the analyzer is immediately followed by
+        a bare 'pass' — every catch logs or is a narrowed typed catch."""
+        import re
+        from pathlib import Path
+        import edgar.documents.utils.toc_analyzer as mod
+        src = Path(mod.__file__).read_text().splitlines()
+        offenders = [i + 1 for i, line in enumerate(src)
+                     if line.strip() == 'except Exception:'
+                     and src[i + 1].strip() == 'pass']
+        assert not offenders, f"silent 'except Exception: pass' at lines {offenders}"