Expand description
Cyberbrain code index. See docs/SPEC.md §10.
find(root, symbol, limit, opts) walks a project tree, extracts definitions with
per-language heuristics ([lang]), matches them against the symbol ([query]) and
returns line ranges the caller reads instead of whole files.
§No persisted index, and why
The index is rebuilt on every call. Measured in release mode on this crate’s own tree
(131 files, 1.4 MiB, 2 688 definitions once target/ and node_modules/ are
gitignored): 14 ms median, of which 3.7 ms is the walk and reading, about 4.5 ms is
regex matching and the rest is lexing for line ranges. A FastAPI backend of 48 files
took 4 ms, a Next.js frontend of 97 files 9 ms. A cache keyed on path, size and mtime
would still have to stat every file to validate itself, so it could only save the
10 ms that are not the walk, and it would add the one failure this feature must not
have: a line range that no longer points at the symbol, handed to a caller who then
reads the wrong slice without knowing. A fresh scan cannot be stale. If a tree ever
grows to where the scan is felt (roughly 100 ms per ten thousand source files), a
cache validated by size+mtime is the next step, and the split into walk / extract /
match leaves room for it. find is not a hook event; a hook that called it would
spend its whole 15 ms budget (SPEC §9.1) on this tree, which is a reason for the
hook not to call it, not for a cache.
§Counts name their boundary (SPEC §14.3)
files_scanned is files whose text reached an extractor. Every other file is under a
reason in Skipped, and a directory the ignore rules kept the walk out of counts
once as an entry that was not entered — the files inside were never looked at, so
no number claims to know how many there were.
Structs§
- Definition
- One definition in the tree. Line numbers are 1-based and
start_line..=end_lineis inclusive;lineis the line that names the symbol and always lies inside the range. - Find
Options - Find
Result - The result of one
find. - Hit
- Scan
- Every definition in the tree, for callers that want the whole index.
- Skipped
- Everything the walk declined, by reason. Every field names the side of the boundary it counts.
Enums§
- DefKind
- What kind of definition a hit is. Serialised by
DefKind::as_str. - Language
- Match
Kind - How a hit matched the query. Ordered best first.
Constants§
- DEFAULT_
MAX_ FILE_ BYTES - Files over this size are not read. A source file this big is generated or minified, and a hit inside it is not a slice anybody reads.
- IGNORE_
FILE - The ignore file honoured at every level of the tree (SPEC §10). gitignore syntax.