Documentation
¶
Overview ¶
Package parser bridges Grove's storage-aware projection to the shared astkit tree-sitter extraction layer. The actual per-language extraction logic lives in astkit/strategies; this file only:
- Maps Grove's language strings (e.g. "javascript") → astkit.LanguageKey.
- Drives the shared parser/registry.
- Projects each astkit.Symbol → core.SymbolRecord, attaching Grove-only fields (ID, FilePath, BlobSHA, Language, Imports, TokenEstimate) and renaming Body→RawText, Exported→Exports, ParentName→ParentSymbol.
Index ¶
- Constants
- func DetectLanguage(path string) string
- func ExtractPlaintext(relPath, blobSHA string, content []byte) []core.SymbolRecord
- func FileBlobSHA(path string) (string, error)
- func IsPlaintext(lang string) bool
- func Supported(path string) bool
- type Engine
- func (e *Engine) ExtractContent(relPath string, content []byte) ([]core.SymbolRecord, error)
- func (e *Engine) ExtractFile(path string, root string) ([]core.SymbolRecord, error)
- func (e *Engine) ParseTree(language string, src []byte) error
- func (e *Engine) References(root, name string) (ReferenceResult, error)
- func (e *Engine) Walk(root string) ([]core.SymbolRecord, int, error)
- type Reference
- type ReferenceResult
Constants ¶
const ( // PlaintextFTSLimit is the maximum bytes stored in the docstring column, // which feeds the search indexes. 64 KB covers nearly all real-world // docs and configs while bounding per-document index cost. PlaintextFTSLimit = 64 * 1024 // PlaintextRawLimit is the maximum bytes stored in raw_text. // Prism uses raw_text for progressive disclosure; 1 MB is sufficient // for the largest policy/swagger/OpenAPI files teams encounter in practice. PlaintextRawLimit = 1024 * 1024 )
const MaxFileSizeBytes int64 = 10 * 1024 * 1024
const PlaintextLanguage = "plaintext"
PlaintextLanguage is the language tag assigned to non-code documents (markdown, YAML, JSON, XML, shell scripts, etc.) that Grove indexes as whole-file document records rather than extracted symbol trees.
Variables ¶
This section is empty.
Functions ¶
func DetectLanguage ¶
DetectLanguage returns the Grove language tag for a file path. Returns "" for unsupported or security-excluded files.
func ExtractPlaintext ¶
func ExtractPlaintext(relPath, blobSHA string, content []byte) []core.SymbolRecord
ExtractPlaintext produces a single whole-file SymbolRecord for non-code documents. The record kind is KindDocument and the language is "plaintext".
Content layout:
- docstring — full text, capped at PlaintextFTSLimit (searchable)
- raw_text — full text, capped at PlaintextRawLimit (Prism disclosure)
- signature — first meaningful line (title / heading / top-level key)
- name — base filename
- qualified_name — repo-relative path (used for path-based queries)
func FileBlobSHA ¶
func IsPlaintext ¶
IsPlaintext reports whether the language tag belongs to the plaintext family.
Types ¶
type Engine ¶
type Engine struct{}
func (*Engine) ExtractContent ¶ added in v0.6.0
ExtractContent extracts symbols from in-memory content as if it lived at relPath (repo-relative, slash-separated). This is how callers preview the symbols a not-yet-written file would index — e.g. a merge driver whose result git only writes to the worktree after the driver exits.
func (*Engine) ExtractFile ¶
func (*Engine) ParseTree ¶
ParseTree validates that src is syntactically valid for the given language. Returns nil on success, a wrapped error if the language is unsupported or the parser reported syntax errors.
func (*Engine) References ¶ added in v0.12.0
func (e *Engine) References(root, name string) (ReferenceResult, error)
References returns the code references to a symbol name across root. It parses each file (so it is grep-with-syntax: comments, strings and javadoc are excluded, unlike textual grep) and attributes each occurrence to its nearest enclosing symbol. It deliberately does NOT resolve which overload/definition a reference binds to — it reports completeness with an ambiguity flag.
`name` may be a bare name ("ValidateToken") or a qualified one ("auth.Service.ValidateToken", "pkg::Type::method") — references position is always the bare leaf identifier, so the qualifier is stripped to the last segment before matching. A byte-level substring pre-filter skips files that cannot contain the name without parsing them, which is what keeps the query fast on large trees (only the handful of files mentioning the name are parsed, not the whole repo).
type Reference ¶ added in v0.12.0
type Reference struct {
File string `json:"file"`
Line int `json:"line"`
Enclosing string `json:"enclosing,omitempty"` // nearest enclosing symbol, if any
}
Reference is one code occurrence of a symbol's name in reference position.
type ReferenceResult ¶ added in v0.12.0
type ReferenceResult struct {
Name string `json:"name"`
DefCount int `json:"defCount"`
Ambiguous bool `json:"ambiguous"`
Refs []Reference `json:"refs"`
}
ReferenceResult answers "where is NAME used?" by name across the repo — the resolution-free reference layer. It is near-complete by construction (every code occurrence of the name), and far more complete than the resolved call graph for types/classes/constants, which calls edges never capture (a class is referenced, not called). DefCount lets the caller tier the answer: exactly one defined symbol with the name => Unambiguous (the references are definitely to it); several => Ambiguous (references are to *some* of them).
Source Files