Solution for gh-ppx_minidebug-84-followup

[lukstafi]

Solution from coder for feature: gh-ppx_minidebug-84-followup

[lukstafi]

Refactoring Suggestions

Post-merge retrospective: what would we do differently if starting from scratch?

Refactoring Suggestions

If starting from scratch, I would...

• Move query row decoding and query SQL fragments in client/query.ml into a small internal submodule (Entry_row) with one canonical column order constant and one decode function, then assert column-count/shape in one place to prevent drift across query call sites.
• Split populate_search_results in client/query.ml the same way we split extract mode: isolate stream scanning, retroactive highlight handling, and propagation orchestration. It is still too monolithic and hard to reason about for edge cases.
• Replace the mutable results_table : (int * int, bool) Hashtbl.t boolean flag with an explicit internal type like highlight_kind = Match | Ancestor; that would make search/extract semantics clearer and reduce accidental misuse at call sites.
• Add a shared internal utility in client/query.ml for "highlight all headers for scope" returning inserted keys, and use it in both search and extract paths so highlight insertion/removal bookkeeping is not duplicated.
• Add focused unit-level tests for propagation behavior without requiring full end-to-end DB creation (e.g. a tiny synthetic fixture DB checked into test/fixtures/), then keep only a small number of full integration tests in test/*.ml.
• Add API-level docs in client/query.mli for DAG semantics (find_scope_header first-only vs find_scope_headers all-parents) and quiet-path stopping rules, because these are subtle and currently mostly implicit in code.
• Consolidate test fixture helpers into a dedicated test utility library module (not just latest-run lookup), including reusable helpers for "find duplicated ancestor", "collect header keys", and deterministic DB path resolution.