Querying the Graph: Seeds, Paths, and Bounded Context

Graphify's query problem begins after the graph has already been built: a natural-language question must select a useful neighborhood without returning the whole repository or hiding how the neighborhood was chosen. This chapter follows that selection from searchable terms to ranked seeds, bounded BFS or DFS traversal, path and node tools, and finally source verification. The goal is not to make every question produce a complete answer. It is to make the next piece of evidence small enough to inspect and explicit enough to challenge.

The distinction matters because a graph can be both too small and too large. A single exact match may omit the caller, dependency, or explanation that gives it meaning. An unconstrained traversal may be technically comprehensive but practically useless, because high-degree hubs and unrelated neighbors consume the reader's attention. Graphify's query surface is designed around that tension.

A question becomes a seed set

A question such as “what connects authentication to the response?” contains two different kinds of language. Some words express the user's intent—connects, uses, calls, or explains. Other words name possible entities, files, or concepts. Graphify begins by turning the question into searchable terms, normalizing punctuation and language-specific forms, and removing common filler words when they do not help identify a node. The aim is not a full semantic interpretation of the sentence. It is a more disciplined way to decide which graph entities should become starting points.

The scoring step then compares the terms with several kinds of node information: labels, identifiers, source paths, and, where available, rationale text. An exact match should outrank a loose substring match. A rare identifier should be more informative than a common word that appears on hundreds of nodes. Graphify uses inverse-document-frequency-style weighting for that reason, giving terms less weight when they occur broadly across the graph. It also maintains a character-trigram index that can narrow candidate nodes for longer searches without pretending that the index itself has determined relevance.

Imagine a reader asking where a validation error becomes an HTTP response. “Validation” may appear in many files, while the name of a response type or handler may be rarer. A useful query should not let the common word dominate merely because it has more textual hits. It should use the distinctive terms to seed the graph, then let the relationships reveal whether the relevant path runs through a handler, an adapter, or a documented policy. If the reader already knows the file but not the symbol, the path itself can help; if they know the symbol but not the file, exact label matching and ambiguity handling matter more. The query mechanism is therefore matching the question's information shape to the graph rather than treating all words as interchangeable.

This separation between candidate generation and scoring is important. A fast index can say which nodes might contain the requested text; the final ranking still applies the graph's matching rules. A path match may be useful when the reader knows where a concept lives but not its exact symbol. A rationale match may recover a node whose label is terse but whose explanation contains the question's vocabulary.