Repository navigation
Seven reading features: entry points, changes tool, churn heat, type map, debug-run walkthrough, value trace, glossary + export - #10
Merged
Conversation
…hey reach a function The overview named one kind of entry point — a function called `main` — so a web service, a CLI or a bot had an empty or wrong "where execution begins", and nothing answered the reader's commonest question: how does execution get to the function I am looking at? - `outline::entry_kind` classifies a function as a main, a route, a command or a handler from its text alone, like `is_test_fn` and for the same reason (the client's index and the server's snapshot must agree): the name (`main` everywhere, the cloud-function `handler`), Rust attributes, Python/TypeScript decorators (their own line or the method's; an argument list over several lines is read whole), Java annotations, Go handler signatures, and the Next.js file conventions. A test is never an entry; neither is anything but a function or method. - `SymbolEntry`, the index cache (version 11) and the wire's `IndexSymbol` carry the kind (protocol v14, snapshot regenerated); the server classifies for a remote project exactly as the client does. - `ProjectCallGraph::paths_from_entries` walks callers breadth-first to the shortest chain from each entry point, mains/routes/commands/handlers before tests, bounded in count and depth. - The Explain panel's call flow gains REACHED FROM: one row per chain, entry first with its kind, every step a button; an entry point says so; a function nothing reaches says that; a test, or a project without any entry point, shows nothing. Memoized per graph and index generation. - The overview prompt lists every kind, mains first, capped at 48 with the rest counted, so a route table does not become the prompt. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
…urrent work changed The WALK tab could review the branch's diff, but the Ask agent had no way to see it: its `history` tool listed one file's commits, so "what did this branch change" and "why was this changed" went unanswered. - `changes` (server agent) reviews the current work against its review base — the branch versus main/master, else the last commit, the same base the review walkthrough uses: the commit messages, the changed files with their status, and the unified diff, truncated to the result cap; with `file`, that one file's whole diff. A file the work leaves alone says so; a path outside the project is refused; a repository with nothing to review says that. Changed files come back as chips. - `git::range_patch_of` narrows the range diff to one pathspec. - The system prompt names the tool and when to reach for it; the Ask panel gives its steps a glyph. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
…hanged Facing a few hundred nodes, a reader had nothing to say where to look first: the maps coloured by language and hierarchy depth, and the lists ranked by fan-in and callers, none of it about where the work is. - `git::churn` counts each file's commits over the last N (300) commits, merges left out, with the time of its latest; `GitOp::Churn` carries it over the wire (protocol v14's snapshot regenerated), validated like the other history limits. - Opening a graph overlay loads it (local git or the remote host's), once per couple of minutes; a project without git simply has none. - Heat: a header toggle colours every map node by its file's change frequency on a log scale — muted for unchanged, warming to the danger colour for the most changed — instead of by language; the scene cache is keyed by the paint so a toggle or a new history repaints at once. - Both overlays' lists gain MOST CHANGED: the hottest files with their counts and how long ago they last changed, each opening the file. - The calls overlay files the entry points (mains, routes, commands, handlers) under their own heading and out of UNCALLED, which no longer has to hedge "entry points / possibly dead". Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
…y relate The overview's "key types" was a list of names; understanding a project's data model meant opening each type and reading its fields. Now a third graph overlay draws the types and their relations, next to the import and call graphs. - `DocItem::refs` (protocol v14's snapshot regenerated): for a type, the identifiers its declaration, its own members (fields, variants, constants — the body less its methods' bodies) and its members' signatures name, in order, capped; field and parameter names, calls and member accesses are told apart from types by the text around them. Computed by `apidoc::build_file`, so a remote project's index carries it. - `typegraph::TypeGraph`: a node per struct, class, enum, interface, trait, union or alias the API index lists; an edge where one names another — `Inherits` from the declaration (extends, implements, with, a Python base, a Rust supertrait or trait impl via the structure index, a C++ base) or `Uses` from the members. Resolved against the project's own type names, so `Vec` and `String` cost nothing. - `Overlay::ProjectTypes`: the map (a node opens its definition at its line; layout nodes now carry one), the list (counts, MOST REFERENCED, BASE TYPES, MOST DEPENDENCIES, MOST CHANGED), a toolbar icon, a View menu item and ⌘⇧T. The index is asked for when stale and the map redrawn when it arrives; the graph is rebuilt only for a new index. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
The debugger showed the live caller of the function being explained, and nothing else of the run survived it: the reader who had just stepped through a callback, a trait method or a dispatch table could not turn what they saw into a tour, and the call graph could not say which of its edges the program had really used. - Every inspected stop is recorded in the run's trace — why the program stopped and the stack it stopped with — up to a cap (then marked cut); a new run starts it over, and it outlives the session. - `walkthrough::from_trace` makes a tour of it without a model: one step per stretch of stops in a function, anchored to the innermost frame in the project, in the run's order, narrated with the stop's reason and the caller. With a model configured, `TRACE_SYSTEM` narrates the same steps, on the run's own anchors; a model that drops or moves steps yields to the plain tour, so the run is never lost. - The debug panel counts the trace's stops and offers "Walk this run"; the WALK tab offers "Walk the last run" and labels `@trace` tours. - The calls overlay lists EXECUTED — the functions the run stopped in, with their counts — and every map rings the files the run went through, keyed by the trace's revision. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
…d on The call graph answers "who calls whom"; the reader's other question, "where does this value come from and where does it go", had only the full-text search. Now an identifier can be traced. - "Trace Value" (the context menu) asks the language server for the identifier's definition and references, then reads each occurrence's line — from an open pane at once, else off disk — and `flow::classify` says what the line does with it: declares or assigns it (and from what: a call, another name, a literal), binds it as a parameter, passes it to a call (which, and as which argument), returns it, branches on it, reaches into it, or reads it. Text, not a parse, in any language; a line the heuristics misread is still shown, as a read. - The FLOW sidebar tab files the occurrences under those roles, each opening its line. A `Passed` row unfolds into the callee: its definition is looked up, the argument's parameter read off the declaration line (`flow::parameter_at`, in each language's style), and that parameter's occurrences hang under it — as deep as the reader follows. A stale answer is dropped by its token. - A remote project's occurrences in files not open here are listed by location, unclassified, and the tab says so. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
…xport of the reading notes A reader meets the same names over and over — the project's types, its modules, its acronyms — and each one cost a jump to its declaration to recall what it was. The glossary (`app::glossary`) collects those terms with a one-line definition in the project's own words: a documented type or acronym's from its doc comment (the API-docs index), a file's or folder's from clew's cached explanation. A name with neither is not a term. The definition shows as the hover's summary line wherever the term is met in another file (a same-file term stays the local peek's), and the ⋯ menu's new Glossary row opens a page listing every term by kind, filterable, each a button to its definition. The glossary is memoized on the docs generation and the explain-cache sequence, so a hover and the page share one build. The ⋯ menu's new "Export Notes…" row (`app::export`) writes what the reader gathered — notes, bookmarks, the reading trail, saved walkthroughs and the glossary — as one Markdown file where the save dialog points, and says where it went (or why not). Both rows have their tutorial step; the menu-rows and stamped-message tests cover the new messages; the page, the hover fallback and the export are tested end to end. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
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
2 participants
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.
Summary
Seven features that shorten the path from "what is this code" to understanding it, one commit each:
6147b5d) — the symbol index classifies where execution enters the project (main, tests, HTTP/CLI handlers, framework decorators, …); the overview lists them and Explain shows how an entry reaches the explained function.changestool for Ask (14631ff) — Ask can answer what the current work (working tree / recent commits) changed, via a new server tool.d8b3f4a) — the project graphs can colour files by how often they changed (GitOp::Churn, protocol v14).2614f55) — a graph of the project's types and their "uses" / "inherits" relations, from the docs index (DocItem.refs), with ⌘⇧T and a toolbar icon.c603e09) — the path a debug run actually took is recorded and turned into a walkthrough.5226abd) — trace a value: where it is set, passed, returned and branched on, expandable across calls.1efe11d) — project terms (types, modules, acronyms) with one-line definitions from doc comments / Explain summaries, shown in the hover and on a Glossary page; ⋯ → Export Notes… writes notes, bookmarks, trail, walkthroughs and glossary to one Markdown file.Protocol:
PROTOCOL_VERSION13 → 14 (IndexSymbol.entry,DocItem.refs,GitOp::Churn/GitResult::Churn); wire snapshot regenerated. Session cache version 10 → 11.Test plan
cargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warnings(backend crates clean; GUI crate only the pre-existing Linux dead-code items)-D warnings --document-private-itemsmain(GUI tests run on macOS in CI)🤖 Generated with Claude Code
https://claude.ai/code/session_01WRJ4sDknvQJ86tFvGydgpf
Generated by Claude Code