Skip to content
Merged
12 changes: 8 additions & 4 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,16 +72,18 @@ corpus of linked documents. Crate `tread`, binary `tread`.
| `src/md/` | `mod.rs` (`parse`), `block.rs`, `inline.rs`, `ast.rs`, `sanitize.rs` |
| `src/csv/` | the CSV foundation: RFC 4180 `parse.rs`, lazy `index.rs` with `index_store.rs` (`RowStore`, re-exported so it stays `csv::index::RowStore`), windowed `read.rs`, `delim.rs`. `RowStore::row` is **bounded**: it spends at most one `MAX_ROW_BYTES` of scanning to find where a row ends and otherwise serves it clipped, because proving where the *last* known row ends is a scan to end-of-file on a file whose tail holds no terminator — which on the paint path is a first frame that never flushes and a `q` that is never read. The index is grammar-agnostic: `RowStore::lines` builds it over the quoting-free `Scanner::lines`, and is the **one** constructor every record-per-line format uses (`.jsonl` and plain text). There is exactly one line indexer in the crate; a second copy would drift, and running the CSV grammar over a log would let one `"` swallow the rest of the file |
| `src/json/` | the JSON foundation: RFC 8259 `parse.rs`, the source-faithful `value.rs` tree, `write.rs`, `error.rs`, and the lazy structural `index.rs` — all iterative, nothing recurses on nesting |
| `src/source/` | the format seam: `Source`, `markdown.rs`, `csv/`, `json/`, `jsonl/`, `jsonrow.rs`, `detect.rs`. Formats are compiled in, never loaded |
| `src/source/` | the format seam: `Source`, `markdown.rs`, `csv/`, `json/`, `jsonl/`, `jsonarray/`, `jsonrow.rs`, `record/`, `detect.rs`. Formats are compiled in, never loaded |
| `src/source/jsonrow.rs` | the **one** JSON tree-row grammar: indent, fold marker, key spelling, collapsed summary, scalar colours, path steps. Both JSON sources build every row through it, and `tests/json_differential.rs` reads the same content both ways and compares — two renderers would drift and the same object would look different depending on which file it came from |
| `src/source/json/` | JSON behind the seam: the lazily indexed `tree.rs` with `ident.rs` (a member's bytes, key and path — **derived** from the parent chain, never stored, or the paths alone cost O(depth²)), the fold state and flatten in `flat.rs`, `render.rs`, the `Source` impl in `view.rs`, and `export.rs` (`--to-jsonl`) |
| `src/source/jsonl/` | `.jsonl` / `.ndjson` behind the seam: a record per line over the *CSV* lazy line index, `rowmap.rs` (which rows an open record owns), `tree.rs` (one iterative walker: count, rows, path, over `jsonrow`'s grammar), `rows.rs`, `view.rs`, and the lens half — `plan.rs` (items: which records share a row, and the two-level row arithmetic) and `lensrow.rs` (the lens state on the source, and the rows it paints) |
| `src/source/record/` | records in general, above any one record *format* (SPEC.md §Lenses). There is **one** record source — `source.rs` (`RecordSource<S>`: state, cache, search sweep), `view.rs` (the `Source` impl), `rows.rs` (summary rows, expansion, outline, `--toc`), `ladder.rs` (`Enter`/`za`: the three levels a record has and what descending one costs), `lensstate.rs` (the lens state and its forwarders), `tree.rs` (one record laid out as tree rows, over `jsonrow`'s grammar) — and what a record *format* supplies is `store.rs`'s `Store`: how many records the index has found, how to push it along inside a byte budget, and record `i` as bytes or as a value. Nothing here opens a file, names a format or mentions a line. The lens machinery under it is `plan.rs` (items: which records share a row, and the row arithmetic — a record's own rows depend on the **width**, because its text is wrapped, so `set_width` re-lays every one without reclassifying anything) with `plan_rows.rs` beside it (the level a record is at, its measured heights, and which of its calls is open — all keyed by *record*, because a step inside an open run is as much a thing a reader opens as a message is) and `plan_block.rs` (where a block starts — a member of an open run is a block, and *everything under that member's row* is in it, never in the run's), `rowmap.rs` (which rows an open record owns; `Plan::extra` is a second one of these, holding the rows a member of an open run shows under itself, so `own`, `inside` and `blocks_of_item` keep the shape they had), `lensrow.rs` (the rows a lens paints, the row-to-record translation under them, and the measurement), `body.rs` (one wrap and one clip for every stretch of text this seam shows — a message, a step's reasoning, a call's argument, its output — with the `⋯ +N lines` row that says what the clip left out; a lens never hides anything), `parts.rs` (the **open level**: a record's tool calls as one row apiece, each opening into its arguments and its output under a row that names it. It decides rows — the columns, the glyph, the inset a member of an open run carries — and nothing about what a record contains, which is the dialect's `detail()`), `ops.rs` (what `zR`, `zM`, `Tab`, `Y` and a fold id off the outline do to a plan), and the shared gutter and fold vocabulary: `marker`/`leaf`, `/4` for a record beside `plan::group_id`'s `g4` for a group, the two spellings that must not collide. `Records` is the trait `lensrow`/`ops` reach records through — `with_value` hands the record to a closure, so it is generic rather than `dyn`: a record can be tens of megabytes and lives behind a `RefCell`, and handing out a clone to read one field would undo the cache. A change all lenses need belongs here, not in a dialect |
| `src/source/jsonl/` | `.jsonl` / `.ndjson`: the `Store` that says a record is a *line*, over the **CSV** lazy line index (`RowStore::lines` — the one line indexer in the crate, called and not copied), plus the parse of one line and the two constructors. Everything else it used to hold is `record/`, shared |
| `src/source/jsonarray/` | records that are the elements of an **array inside a JSON document** (SPEC.md §Lenses, ATIF trajectories): the `Store` over the *existing* lazy structural index (`json::tree::Doc` — a member's byte range, no value built), plus the synthesised record 0 that keeps the document's other top-level keys so a lens hides nothing. Finding the array is a structural scan of the top level — the index knows a member only once it has walked past it — so the first row waits on a byte walk of the file and says so; no record is parsed until it is painted. `At::Root` / `At::Key` is the source's half of `lens::RecordsAt`, and nothing here names a dialect |
| `src/source/text/` | plain text behind the seam (SPEC.md §Plain text): the file's lines, verbatim, over the *CSV* lazy line index — `mod.rs` (state, file access, the tab/control-character painting rule) and `view.rs` (the `Source` impl). No outline, no folds, no links: the honest empty answers. Anything whose extension names no parser lands here, and so does a corpus link to a `.sh` |
| `src/code/` | the language grammars, pure like `md`/`csv`/`json`: a lexer and a declaration recogniser per language (`rust`, `ts`, `py`, `java`), over the shared line arithmetic in `decl.rs`. `docs/code.md` is the contract |
| `src/source/code/` | code behind the seam: rows and colouring (`render.rs`, `paint.rs`), import resolution (`jump.rs`, `tsconfig.rs`, `workspace.rs`), the `Source` impl |
| `src/source/fold.rs` | what folds and what folding hides. Prose infers a section from the next heading; code *states* where a region ends, because a block that ended at the next heading would swallow the statements after it |
| `src/lens/` | the `--lens` seam (SPEC.md §Lenses): `mod.rs` holds `Lens`, `Summary` and the registry; one module per dialect (`agent.rs` — Claude Code session logs). A lens is a **transform over records**, never a `Source`: it says what one record *is* and nothing about rows, folding or search. A record it does not recognise falls back to the generic tree and is never hidden. Adding a dialect is a module plus one line in `LENSES` — `docs/lenses.md` is the contract |
| `src/open.rs` | resolving the input and building the `Box<dyn Source>` behind it; `open/lens.rs` is the one place a `--lens` meets a format |
| `src/lens/` | the `--lens` seam (SPEC.md §Lenses): `mod.rs` holds `Lens`, `Summary`, `RecordsAt` and the registry; one module per dialect (`agent.rs` — Claude Code session logs; `atif.rs` — ATIF trajectories, whose records live inside a document). A lens is a **transform over records**, never a `Source`: it says what one record *is* — including its `Summary::body`, which is a bounded head plus the path back to the text inside the record, never a copy of the message, because a summary is kept for every record — plus the one declaration `records_at()` — where its records live, which is what `src/open/lens.rs` turns into a format and a refusal — and nothing about rows, folding or search. A record it does not recognise falls back to the generic tree and is never hidden. `part.rs` is the row-free vocabulary a dialect answers `detail()` in — `Part::Text` and `Part::Call`, every stretch of text a bounded `Body`, plus `args_of`, the **one** reading of a call's argument list, which both dialects use so an `arguments` that is not the object the schema promises becomes one named row rather than nothing; `agent_parts.rs` is that dialect's half of it, split so both stay under the size limit. Adding a dialect is a module plus one line in `LENSES` — `docs/lenses.md` is the contract |
| `src/open.rs` | building the `Box<dyn Source>` behind an input; `open/input.rs` resolves *what* to open (the path or the pipe, the first bytes, the encoding refusal), and `open/lens.rs` is the one place a `--lens` meets a format — it turns a dialect's `RecordsAt` into a reader and into the refusal for pointing a record-per-line lens at a document, or a document lens at a `.jsonl` |
| `src/render/` | AST + width to styled wrapped lines |
| `src/theme.rs` | palette, heading styles, banner glyphs |
| `src/pager/` | viewport, scrolling, collapse tree, search |
Expand Down Expand Up @@ -155,6 +157,8 @@ TREAD_JS_CORPUS=~/some/node_project cargo test --bin tread a_real_javascript_c
TREAD_PY_CORPUS=/usr/lib/python3.11 cargo test --bin tread a_real_python_corpus -- --nocapture
TREAD_JAVA_CORPUS=~/some/java_project cargo test --bin tread a_real_java_corpus -- --nocapture
TREAD_TS_PROJECT=~/some/ts_project cargo test --bin tread a_real_project_resolves -- --nocapture
TREAD_ATIF_TRAJECTORY=~/some/trajectory.json \
cargo test --bin tread a_real_atif_trajectory -- --nocapture
```

The last reports what fraction of a project's own imports resolve; run it after
Expand Down
23 changes: 18 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,8 +210,8 @@ Exit codes: `0` ok, `1` runtime error, `2` usage error.

| Key | Action |
| --- | --- |
| `j / ↓` | line down |
| `k / ↑` | line up |
| `j / ↓` | one row down |
| `k / ↑` | one row up |
| `d` | half page down |
| `u` | half page up |
| `space / f` | page down |
Expand All @@ -225,13 +225,14 @@ Exit codes: `0` ok, `1` runtime error, `2` usage error.
| `w` | widen the column under the cursor to fit the screen |
| `a` | show or hide what this view hides (dotfiles, code bodies) |
| `za` | toggle the section at the cursor |
| `Enter` | follow the focused link, open the row, else fold |
| `Enter` | follow the focused link, else one level into the row |
| `r` | show the raw record under the cursor, from either level |
| `zo` | open the section at the cursor |
| `zc` | close the section at the cursor |
| `zM` | collapse every section |
| `zR` | expand every section |
| `Tab` | next heading |
| `S-Tab` | previous heading |
| `Tab` | next heading (next block under a lens) |
| `S-Tab` | previous heading (previous block under a lens) |
| `o` | outline overlay |
| `/` | search forward |
| `?` | search backward |
Expand Down Expand Up @@ -407,6 +408,18 @@ bookkeeping — collapse into one row that opens with `Enter`. `Tab` steps
between messages and runs rather than through what a run folded away, and a
search hit inside a folded run opens it.

**A record has two levels, and `Enter` toggles them.** The row is a headline
with what was said — or, on a step, what it was thinking — clipped underneath.
`Enter` opens that whole, and lists the record's tool calls as tool calls:
`▸ bash cargo test -q → 32 lines`, one to a line. `Enter` on *that* line shows
the arguments the call was made with and the output it returned, clipped the
same way. `Enter` again is back to the clip. The raw record is `r`, from either
level and back: one key reads the record, the other shows its bytes, and
neither undoes the other. `r` is about records, so in a format that has none —
markdown, CSV, code, plain text, a JSON document — it says `nothing to open
here`; on a `.jsonl` with no lens it opens the record's tree, which is all a row
there is.

A lens only ever *adds* interpretation. A record it does not recognise renders
exactly as it would without one, and every summary row still opens into the
whole record: `Y` on a run copies every record in it as JSON. Reading a real
Expand Down
Loading
Loading