Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,14 +75,14 @@ corpus of linked documents. Crate `tread`, binary `tread`.
| `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/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/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), `folds.rs` (the fold half of it: what folds, what a fold hides, and the fold state a session saves — `view.rs` forwards to it), `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`, `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/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; `usage_agent.rs` / `usage_atif.rs` — the same two files read as what each record *spent*, over the shared `usage.rs`, which owns the counters, the exact total and the one spelling of the fixed-width numeric block. Two entries rather than one because `records_at()` is a single answer and a `Lines` lens may not be pointed at 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. `lens::tokens` is the **one** spelling of a token count — floored, never wider than four columns — because the group row and the status bar spell the same number a record row does and two spellings would drift. 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 |
Expand Down Expand Up @@ -159,8 +159,13 @@ TREAD_JAVA_CORPUS=~/some/java_project cargo test --bin tread a_real_java_corpus
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
TREAD_AGENT_CORPUS=~/.claude/projects cargo test --bin tread a_real_agent_corpus -- --nocapture
```

The last two sweep **private** files. They read and measure; they print counts
only, and nothing from either is ever copied into a fixture, a doc or a commit
message.

The last reports what fraction of a project's own imports resolve; run it after
touching resolution. It caught an absolute path where a relative one was needed,
a corpus rooted at the wrong directory, and an extension substituted rather than
Expand Down
15 changes: 14 additions & 1 deletion SPEC.md
Original file line number Diff line number Diff line change
Expand Up @@ -402,7 +402,20 @@ run is a conversation, and what a reader wants is the conversation with the
mechanics folded away. Messages stay visible; consecutive tool calls and their
results collapse into one summary row (`⟨6 steps · 4 tool calls⟩`) that opens.
Two dialects read one today — `agent` for Claude Code session logs, `atif` for
ATIF trajectories — and a third is a module and a line.
ATIF trajectories — and another is a module and a line.

A lens says what a record *is*, and there is more than one honest answer for the
same file. `usage` and `usage-atif` read those same two shapes as what each
record **spent**: a fixed-width block of token counters, then what the record
did, with a record that spent nothing showing its kind and no number columns at
all. A printed number means the format recorded that value, `-` means this
record did not record a field its format has, and an absent column means the
format has no such field — the middle of those three is a defensive path rather
than observed behaviour: no measured record has yet carried some of its format's
counters and not the others, and it is held to by tests alone. Counts are
floored to four columns, so a row that says
`18k` promises at least 18,000; the exact integers are on the level under it,
and the exact sums are on the run's row and in the status bar.

**A row is a headline; the record is under it.** A summary row is one line —
who, when, what — and for a message that `what` **is the message's own first
Expand Down
Loading
Loading