test(audit): coverage for schedule CLI, perf-vis, VLM extraction, PDF gen/export; fix silent table-row loss

[kovtcharov]

Closes #1995, #1997, #1998, #2002, #2003 (weekly-audit zero-coverage findings).

Five modules where a parsing or formatting bug would ship silently — the gaia schedule CLI dispatch, the perf-log parser behind gaia perf-vis, the VLM structured-extraction parsers, the synthetic-PDF eval corpus generator, and the summarizer PDF export — now have 102 unit tests. Writing them immediately caught a real production bug: when a VLM wrapped a table's JSON array in any chatter ("Sure! Here's the table: [...]"), extract_json_from_text parsed only the first row object and extract_table silently returned [] — every row dropped, exactly the corruption #1997 warned about. Fixed in gaia.utils.parsing (now extracts top-level arrays too, with regression tests; all existing callers type-check the result, and the EMR suite still passes).

Tests assert the outgoing call shape at mocked boundaries (#1655 rule) — e.g. the schedule tests drive the real argparse parser and assert the constructed Schedule/store arguments, and the PDF tests validate output by reopening the files with pypdf. No LLM or Lemonade server needed anywhere.

Test plan

• python -m pytest tests/unit/cli/test_cli_schedule.py tests/unit/test_perf_analysis.py tests/unit/test_structured_vlm_extraction.py tests/unit/eval/test_pdf_document_generator.py tests/unit/test_pdf_formatter.py tests/unit/test_file_watcher.py → 162 passed
• test_extract_table_strips_surrounding_chatter fails without the parsing fix (reverts red)
• python util/lint.py --all passes

[github-actions]

Verdict: Approve with suggestions

Strong test-coverage PR (102 new unit tests across five zero-coverage modules) that also fixes a real bug: a VLM wrapping a table's JSON array in chatter used to have every row after the first silently dropped. The parsing fix is sound, and the tests are genuinely good — they assert outgoing call shape at mocked boundaries (the #1655 rule) and reopen generated PDFs with pypdf rather than trusting a mock.

One thing worth addressing: the PR says "all existing callers type-check the result," but the EMR patient-extraction caller does not. extract_json_from_text can now return a list, and that caller calls .get(...) on the result unconditionally — so a VLM that wraps the patient object in an array (e.g. [{...}]) would crash with AttributeError instead of the old behavior of returning the first object. It's an edge path and the EMR suite passes because no test feeds a top-level array, but it's exactly the "green tests, still breaks" gap. A one-line isinstance guard closes it. Not a merge blocker for this test PR, but worth a quick fix here or a fast follow-up.

🔍 Technical details

🟡 Important

EMR caller doesn't guard against the new list return type (hub/agents/python/emr/gaia_agent_emr/agent.py:1098)

The VLM callers in src/gaia/vlm/structured_extraction.py (297/360/438/598) all isinstance-check before use, so they're safe. But _parse_extraction only checks is None and then does result.get("phone"):

result = extract_json_from_text(raw_text)
if result is None:
    logger.warning("No valid JSON found in extraction")
    return None
if not result.get("phone"):   # AttributeError if result is a list

Before this PR, an embedded array returned the first row object (a dict), so this never fired on chatter-wrapped output; now it returns the whole list. A form-extraction VLM that emits [{...}] (a patient object wrapped in an array) would reach this line and crash. Suggested guard:

        result = extract_json_from_text(raw_text)
        if not isinstance(result, dict):
            logger.warning("No valid JSON object found in extraction")
            return None

The Optional[Dict[str, Any]] return annotation on _parse_extraction (line 1095) already promises this. (Strictly, the top-level json.loads(text) path at parsing.py:88 could already return a list for a bare-array input, so this is a pre-existing latent gap — but the PR widens the surface enough that it's worth closing now.)

🟢 Minor

Behavior change when a valid array and valid object both appear (src/gaia/utils/parsing.py:95) — candidates are tried in open-position order, so if a valid JSON array opens before a valid object, the array now wins where the object used to. The dict-expecting callers all isinstance-check and degrade gracefully, so no crash — just worth being aware the "first bracket wins" tie-break is intentional. No change needed.

Strengths

• The _extract_balanced_json refactor cleanly generalizes the balanced-bracket scan to both {} and [] without duplicating the string/escape handling, and the "scan only { drops array rows" WHY comment names the exact invariant.
• Tests exercise cold/edge states the mocks would otherwise mask: empty content, missing metadata, malformed perf-log lines, zero-total pie slices, Agg-backend show=True non-hang. test_extract_object_after_prose_bracket specifically covers the stray-[-in-prose regression the new ordering could have introduced.
• Boundary assertions check the constructed Schedule/store-call arguments and reopen PDFs with pypdf rather than asserting "a mock was called" — the gaia init --profile npu fails with status 400 (missing user. prefix for model name) #1655 discipline applied correctly.