Structured summary segments#91
Merged
Merged
Conversation
DiffNode.summary becomes Option<Summary>: an ordered list of typed
Segments (Text, Path{value, snapshot}, Uint, Float). Renderers format
each segment by its type instead of scanning prose for numbers to group.
A Uint is always digit-grouped; Text and Path values are verbatim, so
years in folder names and other non-count digits are never mangled.
Rename/move/copy detectors emit Path segments carrying a snapshot side,
so the renderer never recognizes the "move" concept or string-matches
path-statement prefixes (the prior `humanize_numbers` prose scan and the
path-statement detection are gone). Producers own their concept wording;
the renderer owns typography. This composes with plugin-defined actions.
A plain string still works via `impl Into<Summary>` (one Text segment);
`Summary::count(n, noun)` builds the common "{n} rows" shape with grouping
and pluralization, and `text()` coalesces so it costs nothing on the wire.
Annotation trailers (tabular_summary/content_summary) stay plain text.
See docs/adr/2026-06-03-structured-summary-segments.md.
Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Trying to add commas to long numbers in markdown output exposed a basic issue -- by the time log strings get from transformers to renderers, there isn't enough type information to format numbers properly. "300000 rows" should have a comma but "02-04-2000" shouldn't, and adding special cases to try to guess type info is unworkable.
This patch lets transformers emit structured messages with text, path, int, and float components, so they can emit [pluralize(300000, "row), " moved"] or [path(foo, left), " moved to ", path(bar, right)] or whatever. The renderer can apply whatever humanization or localization or link rendering or whatever it wants.
We can add additional types if upstream plugins need to support some other type of data, like dates or file sizes or whatever.
--
Summary
DiffNode.summary: Option<String>withOption<Summary>— an ordered list of typedSegments (Text,Path { value, snapshot },Uint,Float). Renderers format each segment by its type instead of scanning prose to decide which digit runs to group.Uintis always digit-grouped;Text/Pathvalues are verbatim, so years in folder names and other non-count digits are never mangled (thehumanize_numbersprose scan is gone for summaries).Pathsegments with asnapshotside. The renderer never recognizes the "move" concept or string-matches"Moved from "prefixes — producers own their concept wording, the renderer owns typography, and this composes with plugin-defined actions.Ergonomics
impl Into<Summary>(oneTextsegment), so summary-less producers are untouched.Summary::count(n, noun)builds the common"{n} rows"shape with grouping + pluralization;text()coalesces adjacent text socount()costs nothing on the wire.tabular_summary/content_summary) stay plain text by design (read with.as_str()by the folder-move detector); documented in the ADR.Notes
summaryas a typed segment array (schema doc regenerated); machine consumers can read segments directly or flatten via plain text.Currency/Percentenum) are indocs/adr/2026-06-03-structured-summary-segments.md.