Module coalesce 

Cross-source diagnostic coalescing.

When a single underlying problem produces a diagnostic on many pages — for example, one bad theme: key in _quarto.yml triggering Q-14-1 once per rendered page — the renderer should collapse them into a single emission that lists the affected pages, rather than printing the same ariadne block hundreds of times.

The primary key is the source location

Two diagnostics whose location resolves to the same source span in the same file are presumed to be the same error and are grouped together. We deliberately do not include the code or title in the grouping key — the source location alone is the relation’s primary key (decision recorded in claude-notes/plans/2026-05-22-theme-diagnostic-epic.md).

If two unrelated checks ever land at the same span this is a design risk; the v1 cost (one merged emission with a possibly mixed-content representative) is low. We will widen the key to (location, code) if it turns out to bite.

What does not coalesce

Diagnostics whose location is one of:

• None,
• SourceInfo::Concat, or
• SourceInfo::FilterProvenance,

pass through as singleton groups (one entry each). These shapes don’t reduce to a single contiguous byte range, so we can’t form a stable group key for them. This is the same conservative contract as SourceInfo::resolve_byte_range.

Structs

CoalescedDiagnostic

One entry from a coalesced render summary.

Constants

AFFECTED_FILES_CAP

Maximum number of file names rendered inline in the “Affected files:” tail before switching to “… (and N others)”.

Functions

coalesce_by_source

Group the input by source location and return one CoalescedDiagnostic per group, in encounter order.