Module repograph

Expand description

Reading a code graph back as answers.

ingest-git writes a repository into the graph; this module reads it out again, in the shapes a person or an assistant asks for. Each tool computes a plain data structure and a renderer turns it into a short digest, so the same answer serves a CLI, an HTTP response and an MCP tool without being computed three ways.

Tool	Answers
`explore`	one target from as many sides as asked for: the three below in one call
`repo_map`	what is this repository, in one screen
`brief`	the same, for the start of a session, in a fixed byte budget
`context`	everything known about one file or symbol
`impact`	what else the files in a diff reach
`owners`	who has written a file, and when
`why`	what links two things, with the evidence
`recall::recall_digest`	which nodes a topic is closest to
`remember::remember`	write a note the graph can later recall
`stale_concepts`	which learned concepts have drifted from their sources

rules holds the about_<label> and concept_sources rule definitions both structure::ensure_rules_and_fulltext (CLI) and remember::remember need, so the two cannot declare them differently.

Two rules hold across every tool here. The output is deterministic for the same store state and the same caller-supplied “now”: collections are sorted, ties break on the key, floats print at a fixed precision, and every answer is decided by the graph. The one value that is not is how long ago the store was synced, which is measured against the system clock unless the caller pins the time — see MapOptions::now_ts. And every string that came out of the graph passes through sanitize before it reaches a rendered line, so repository content cannot forge a header or a line break in an assistant’s context.

context is the one tool that reads anything outside the graph: the source it quotes comes from the working tree, so what it shows is what is on disk now. It quotes it only when asked — context_with with ContextOptions::source — and otherwise answers with a pointer to it.

Re-exports§

pub use recall::identifier_terms;
pub use recall::or_query;
pub use recall::recall_digest;
pub use recall::HINT;
pub use recall::MAX_HITS;
pub use recall::MAX_OUTPUT_BYTES;
pub use recall::MAX_QUERY_TERMS;
pub use recall::MIN_HIT_SCORE;
pub use recall::UNTRUSTED_FRAMING;
pub use remember::remember;
pub use remember::RememberInput;
pub use remember::NOTE_KINDS;
pub use render::cap_lines;
pub use render::render_brief;
pub use render::render_context;
pub use render::render_explore;
pub use render::render_impact;
pub use render::render_map;
pub use render::render_owners;
pub use render::render_why;
pub use render::sanitize;
pub use render::DEFAULT_EXPLORE_BYTES;
pub use render::EMPTY_BRIEF;
pub use render::MAX_BRIEF_BYTES;
pub use render::MAX_CONTEXT_LINES;
pub use render::MAX_MAP_LINES;
pub use render::MAX_TOOL_LINES;

Modules§

recall: recall — a short list of pointers to the graph nodes a prompt names.
remember: remember — write a Note the graph can later recall.
render: Turning graph facts into lines an assistant reads.
rules: Rule definitions more than one write path needs to agree on.

Structs§

BriefOptions: How much of each ranking the brief lists, and how long it may take.
BriefReport: The repository, as a session starts.
CallSites: Everywhere one file calls the target.
ContextOptions: What a context call reads beyond the graph.
ContextReport: One file or symbol, from every side the graph can see it.
EdgeTypeBrief: One edge type of a memory store’s schema: what derives it, what it runs between, and how many there are.
ExploreReport: One target, from as many sides as the Depth asked for.
FileImpact: What changing one file reaches.
ImpactOptions: How much of the graph one impact call reports per file.
ImpactReport: What a set of changed files reaches.
LabelBrief: One label of a memory store’s schema: what it is called, how many nodes carry it, and every property name any of them has.
MapCommunity: One group of files that change and import together.
MapOptions: What repo_map is allowed to spend and how much it may print.
OwnersReport: Who has written a file, and when.
Partner: One file the change reaches, and whether the caller has it open already.
Recipe: One question kind and the single call that answers it, with the store’s own keys, labels and edge types already substituted in.
RepoMap: The repository, summarised.
SchemaBrief: What a memory store is: its labels, its edge types, how deep its history runs, who may read it, and the call that answers each kind of question.
SharedCommits: How often two files were touched by the same commit, and by which commits.
SyncInfo: How current the graph is: the sha it was synced to, and how long ago that sync ran.
WhyLink: One rule-written edge, and what makes it true.
WhyReport: How a and b are linked, if they are.

Enums§

Depth: How much of the answer one explore call computes.
Target: What a context call was asked about, once resolved.

Constants§

DEFAULT_EXCLUDES: The paths a repository carries that are not its source: build output, vendored dependencies, generated bundles, and lockfiles nobody reads.
MAX_HOPS: Longest chain a why fallback will look for.
MAX_SOURCE_LINES: Source lines quoted at most, whichever end of a symbol they come from.
MIN_SHARED_COMMITS: Fewest commits two files must share before impact names one for the other on count alone. Two is a coincidence; three is a habit.
PATH_EDGES: The edge types a path may be walked over, in the order the digests name them. Every one of them says one part of a repository depends on, changes with, or talks about another.
QUARTERS: Quarters of history the report covers, counting back from the one “now” falls in.

Functions§

brief: Summarise the store for the start of a session.
context: Everything known about target, with the body quoted.
context_with: Everything known about target.
explore: Everything depth asks for about target.
impact: What changing files reaches, one report per file.
named_symbols: Symbols whose bare name is name, by key.
owners: Who wrote path.
path_excluded: Whether path matches any of patterns.
repo_map: Summarise the repository the store was built from.
shortest_path: The shortest chain of edge_types edges from a to b, as (edge type, node reached) hops — so a two-hop answer is [(IMPORTS, x), (CO_CHANGED, b)] and a is the caller’s own starting point.
stale_concepts: Concepts whose recorded source hashes no longer match the files they were learned from, as (concept key, reason), sorted by key.
why: Why a and b are linked.