Documentation
¶
Overview ¶
Package codemap produces a compact structural outline of a single source file — every top-level declaration and the line range it occupies — so an agent can jump straight to the region it needs with a bounded read instead of pulling the whole file into context.
Outlines are computed on demand, not indexed. Tree-sitter parses a typical source file in single-digit milliseconds, which is far below the cost of the tool call that asks for it, and parsing fresh buys the property that matters most here: the line ranges always describe the file as it is right now. There is no store to migrate, nothing to invalidate when a file is edited, and no way for a stale range to send a reader to the wrong code.
Index ¶
Constants ¶
const ( // MaxFileSize bounds what Outline will parse. Files past this are almost // always generated or minified — bundles under web/dist, vendored blobs — // where parsing costs real time and the outline is unusable anyway. MaxFileSize = 2 << 20 // 2 MiB // MaxSymbols caps a single outline. A file with more declarations than this // is not one an agent should be navigating symbol-by-symbol, and an // unbounded outline would reintroduce the context flooding this package // exists to prevent. The overflow count is reported rather than dropped // silently. MaxSymbols = 400 )
Variables ¶
var ErrBinary = errors.New("binary file")
ErrBinary is returned for files holding NUL bytes.
Functions ¶
func Render ¶
Render formats a FileMap for a model to read.
The output is plain text rather than the JSON the pdf_index tool returns. That is a deliberate break from the neighbouring tool: JSON spends roughly three times the tokens on braces, quotes and repeated key names to carry the same fields, and token economy is the entire reason this tool exists. A model reads an aligned two-column table just as reliably.
Types ¶
type FileMap ¶
type FileMap struct {
Path string
Lang string
TotalLines int
Symbols []*Symbol
// Omitted counts symbols dropped by the MaxSymbols cap.
Omitted int
// Fallback is true when no grammar covered this extension and the
// heuristic scanner produced the outline.
Fallback bool
// ParseError is true when tree-sitter hit a syntax error. The outline is
// still usable — tree-sitter recovers and keeps going — but it may be
// missing declarations after the damaged region, and a reader deserves to
// know that before trusting a gap.
ParseError bool
}
FileMap is the outline of one file.
type Symbol ¶
type Symbol struct {
Kind string // func, method, type, const, var, import, and fallback kinds
Name string // primary identifier; empty for import blocks
Signature string // rendered display form, already collapsed and capped
Doc string // first line of the doc comment, markers stripped
StartLine int
EndLine int
// Depth is how many symbols enclose this one — 0 at file scope, 1 for a
// class member. Rendered as indentation.
Depth int
}
Symbol is one declaration in a file.
StartLine and EndLine are 1-based and inclusive, and StartLine includes any doc comment attached to the declaration: the comment is the part a reader most needs and excluding it would make every jump a two-step operation.
type TooLargeError ¶
type TooLargeError struct {
Size int64
}
TooLargeError reports a file above MaxFileSize.
func (*TooLargeError) Error ¶
func (e *TooLargeError) Error() string
Source Files