headson: Instructions file for Claude Code

headson — AGENTS Guide

This is a distilled, action-oriented guide for agents working on headson. Use it to keep changes aligned with how the tool is meant to behave.

Mission

• headson is a structure-aware head/tail for JSON, YAML, and text: given a byte/char/line budget, emit a compact preview that preserves tree shape and surfaces representative values (see README.md).
• Ships as a Rust CLI (hson) and ABI3 Python bindings (headson.summarize(...)) so the same renderer can be embedded in shells, scripts, or notebooks.

Primary Surfaces to Mind

• CLI (src/main.rs): Clap parser for budgets, format/template/style selection, color controls, compact/no-newline toggles, head/tail skew, multi-input filesets. Detects binaries via content_inspector; prints stdout preview and stderr notices.
• Library (src/lib.rs): Entry headson(InputKind, RenderConfig, PriorityConfig, Budgets) -> String. InputKind covers Json, Yaml, Text { mode }, and multi-file Fileset. TextMode distinguishes plain text vs. code-like (indent-aware, atomic lines).
• Python bindings (python/src/lib.rs, python/README.md): headson.summarize mirrors CLI knobs. Wheels via maturin; parity tests in tests_py/.

Core Pipeline (keep behaviors intact)

1. Ingest (src/ingest): Normalize into JsonTreeArena with flat node/child arrays + metadata for filesets and code-aware rendering. Formats:
   • JSON: simd-json + Serde DeserializeSeed builder (ingest/formats/json) that can pre-sample arrays.
   • YAML: yaml-rust2 loader (ingest/formats/yaml) supporting multi-doc inputs (wrapped into arrays).
   • Text: heuristic builder (ingest/formats/text) that treats lines independently or, in CodeLike, builds indentation trees, keeps lines atomic, and stores the full line list for highlighting.
   • Filesets: ingest/fileset.rs merges per-file arenas under a synthetic object root; remembers filenames for section headers. Callers supply FilesetInputKind per file.
2. Priority Ordering (src/order): build_order scores nodes so top-level structure survives tight budgets. Arrays bias head/mid/tail per PriorityConfig; objects keep key order; strings expand by grapheme (capped via max_string_graphemes); filesets interleave round-robin; code-aware heuristics boost block-introducing lines and penalize blanks.
3. Budget Search (src/pruner/budget.rs::find_largest_render_under_budgets): Binary-search for the largest “top K nodes” that fit bytes/chars/lines. Measurements disable colors and optional fileset headers for exact counts (fileset-tree budgets are measured directly from the tree render; scaffolding lines are only charged when headers are charged). Once best K is found, ancestors/topology are reinserted. CLI --debug re-renders without color and emits JSON traces via debug::emit_render_debug.
4. Rendering (src/serialization): Templates for strict JSON, pseudo (default), JS-with-comments (detailed), YAML, raw Text, and Code (line numbers + syntect highlight). Out writer centralizes whitespace/newline/omission markers/colors/line-number gutters. Fileset helpers print section headers/summaries unless suppressed; omission markers vary by style.