Module report_format 

Serializing a Report to text, JSON, JSONL, and YAML.

Formats are serializations, not features: every view renders in every format, so a caller picks the shape of the answer and the shape of the bytes independently.

Output design system

Keep measured results and explanatory diagnostics separate. Renderers return only result data; frontends route the categorized messages from diagnostic_lines and report_warnings to their diagnostic stream. Machine formats must remain parseable and ANSI-free.

Human rows use bright bold cyan names, ordinary foreground file counts, and gray parenthetical detail. Ignored amounts embedded in a row are always gray parentheses; file counts belong directly after the name, outside parentheses. Secondary breakdowns such as nonblank/blank counts use the same gray parenthetical role. Human directory names have a gray slash except . and ... Directly or ancestrally gitignored directories use regular, nonbold cyan; merely containing ignored files does not change a directory name, and file-name styling is unchanged. Sizes >= 1 GiB are bold even in gray details; zero sizes and exact shares below 1% are gray. Pad cells before applying ANSI styles. Colored bars use green solid non-gitignored and shaded gitignored usage, with dim green light-shade cells for unused width. Plain bars keep their original glyphs. Human tree bar width is caller-selectable, including zero to remove the bar and its gutter; machine formats and non-tree views ignore it. Human integer quantities share one grouping policy through human_count and human_count_u128. Every human byte quantity, including cache rows and lifecycle totals, uses styled_bytes for its units and zero/large-value emphasis. Machine fields retain exact integer bytes.

Tree columns are bar, root percentage, size, then indented name. One remainder row per tree uses those same columns and quantity styles for unlisted root branches. Its … and prefix is gray; the recursive hidden file count uses normal foreground. That usage is already included in directory totals. Unknown coverage must show unknown size and no fabricated bar or percentage. Keep rerun flags out of rows: collect applicable remedies once per report in report_epilogue.

The category, ordering, and debugging contract lives beside that collector; CLI stream/color handling lives in write_report_diagnostics. The contributor guide is docs/project/architecture/fdu-output-design.md. Changes must keep the shared golden corpus, Python parity, and terminal stream/color assertions consistent.

Why these are hand-written

serde plus a JSON crate plus a YAML crate would be three dependency additions — and the maintained-YAML question is genuinely unsettled, since serde_yaml is unmaintained. The schema here is small, closed, and fully known at compile time, the crate already hand-writes its JSON, and hand-writing keeps the machine formats provably free of a serializer’s own opinions about key order and number formatting. Key order is fixed by the code, which is what makes the goldens byte-stable.

Structs

DiagnosticLines

Human diagnostics retain categories rather than parsing rendered text.

RenderOptions

Presentation choices for a human report; machine formats ignore both fields.

Enums

Format

How a report is serialized.

Constants

CACHE_SCHEMA

Machine-output schema identity for cache status.

CONTENT_REPORT_SCHEMA

All reports now use one shape-versioned schema regardless of requested analyzers.

MAX_BAR_SIZE

Maximum tree bar width accepted by the human renderer. Bounds decoration allocation without changing measured report data.

REPORT_SCHEMA

Machine-output schema identity.

STREAM_SCHEMA

Streaming-output schema identity.

STYLE_CATEGORY

Category labels keep ordinary cyan; bold bright cyan identifies names.

STYLE_DETAIL

Secondary information: parenthetical detail, omissions, notes, tips, and telemetry. Keep this gray and non-bold except for the shared >= 1 GiB size emphasis.

STYLE_HEADING

The all-caps label naming which view a block of text output belongs to.

STYLE_NAME

Directory names in a tree, so structure reads at a glance.

Functions

byte_style

The shared human byte color role: zero is gray; large values are bold, including gray details. The threshold uses exact bytes, not the rounded display unit.

diagnostic_lines

Categorized messages for frontends that insert operational warnings before tips.

diagnostics

Factual notes, the report’s own warnings, then actionable tips, for a frontend’s diagnostic stream.

document_start

Start one document in a multi-document stream for format.

escaped_human

Escape controls before styling so an entry cannot move a cursor or add a row.

flat_diagnostic_lines

Categorized flat-output diagnostics; paths and long rows stay alone on stdout.

flat_diagnostics

Notes, the report’s warnings, and tips excluded from flat stdout, for a frontend’s diagnostic stream.

human_bytes

Render a byte count at human scale, the way every fdu report does.

human_count

Render a count with thousands separators, the way every fdu report does.

human_count_u128

Group a full-width count using the same human policy as human_count.

is_lossy

Whether a path renders losslessly as UTF-8.

paint

Wrap text in a style when colour is on.

render

Render a report in the requested format.

render_cache_status

Render cache status in any format.

render_cache_status_with_options

Render cache status with the same human color roles as report rows. Machine formats ignore the presentation options; cache text has no usage bar.

render_change

Render one streamed change as a tagged record.

render_with_options

Render with explicit human presentation choices.

report_notes

Facts about coverage and presentation, without suggestions or run telemetry.

report_tips

Distinct actionable suggestions in stable order, using the caller’s vocabulary.

report_warnings

Conditions of the answer itself that a reader must not miss, which quiet output keeps.

styled_bytes

Render a human byte quantity after padding with the shared size and emphasis rules. Plain and structured numbers never depend on styling.

watch_rule

The rule drawn above a watch repaint, carrying the instant it was rendered.

watch_rule_nanos

The watch repaint rule for an integer nanosecond timestamp.

write

Write a report directly to an output stream.

write_with_options

Write with explicit human presentation choices.