codeintel

package
v0.53.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source
const (
	RefDef  = "def"
	RefCall = "call"
	RefSel  = "sel"
	RefRef  = "ref"
)

The classes a reference is reported as. They tell a definition from a use without type information: "def" is a binding position, "call" a call of the name, "sel" a selector use of it (x.Name, pkg.Name) and "ref" anything else.

View Source
const (
	SymbolFunc      = "func"
	SymbolMethod    = "method"
	SymbolType      = "type"
	SymbolConst     = "const"
	SymbolVar       = "var"
	SymbolClass     = "class"
	SymbolInterface = "interface"
	SymbolEnum      = "enum"
	SymbolRecord    = "record"
	// SymbolTrait is PHP's trait, which is neither a class nor an interface: its
	// own kind keeps a listing honest (a language-specific kind, like the ones
	// ctags reports and the vocabulary does not know).
	SymbolTrait = "trait"
	// SymbolSection is a configuration file's table or mapping node: a TOML
	// [table] / [[array.of.tables]] header, or a YAML key whose value is a
	// mapping (a server: block). It is the closest of the vocabulary - a
	// namespace names a scope the same way (see phpSymbols' namespace rule) -, and
	// it is what file_symbols' kind filter can select: "section" answers "which
	// tables/blocks does this config declare".
	SymbolSection = "section"
	// SymbolKey is a configuration file's leaf key: a YAML/TOML entry whose value
	// is a scalar (or an array of scalars), named by its full dotted key path
	// (server.http.port). A config file's keys are its declarations.
	SymbolKey = "key"
)

The kinds the extractors report. Go keeps its own vocabulary (func/method/type/const/var), the other languages theirs (class, interface, enum, record, trait); file_symbols' kind filter accepts either.

View Source
const (
	// ConfigMaxKeys caps the keys one configuration file lists. A file with more
	// is answered with its first keys and a note naming file_grep: the model
	// narrows the key instead of reading a k8s manifest whole.
	ConfigMaxKeys = 300
	// ConfigMaxDepth caps the key depth one configuration file lists (a YAML
	// mapping level, or a TOML path segment). Deeper keys are counted and the
	// note says so.
	ConfigMaxDepth = 4
)
View Source
const (
	// BlocksBrace is a brace-delimited language (C#, Kotlin, C/C++,
	// JavaScript/TypeScript, Java): the brace depth tells a type body from a
	// function body.
	BlocksBrace = "brace"
	// BlocksIndent is an indentation-delimited language (Python): a block ends
	// where a line is no deeper than its first line.
	BlocksIndent = "indent"
	// BlocksEndKeyword is a language whose blocks a keyword closes (Ruby's end):
	// an opener line deepens the stack, the keyword pops it.
	BlocksEndKeyword = "end_keyword"
)

The block styles a rule language declares.

View Source
const MaxGrepLineBytes = 300

MaxGrepLineBytes trims the very long matching lines (minified files) one reference reports. It is the cap file_grep applies to the lines it shows, and the tool layer reads it from here so the two never drift apart.

View Source
const (

	// RareDropUses is how often a variable qualifier may occur and still have
	// its lines shown: a name used once or twice (child.Run) is likely a
	// specific value, while t.Run or cmd.Run in bulk is another object.
	RareDropUses = 2
)
View Source
const RuleSourceBuiltin = "builtin"

RuleSourceBuiltin marks a rule that ships with the binary.

View Source
const RuleSourceCode = "code"

RuleSourceCode marks a language whose extractor stays in Go code.

Variables

SymbolKinds is the whole kind vocabulary, in the order the messages list it.

Functions

func BareRefClass

func BareRefClass(line, name string) string

BareRefClass labels a fallback line from its text: def after a declaration keyword, call when the name is followed by "(", else ref. The classes keep the result readable (a Rust "pub fn file_type" is not one of its callers); they are not a parse.

func DeclLineLanguages

func DeclLineLanguages() string

DeclLineLanguages names, in registry order, the languages whose declarations come from declaration lines rather than a parser: the tool descriptions and the approx note list them.

func FocusedTestPattern

func FocusedTestPattern() *regexp.Regexp

FocusedTestPattern matches the shell commands of a test run limited to some tests (go test -run, pytest -k, maven -Dtest, gradle --tests, ...); such a run is no proof that the suite passes, so the trace analysis does not take one for the first green run.

func InTestDir

func InTestDir(rel string) bool

InTestDir reports whether a fallback file sits under a test directory (tests/, test/, __tests__/, spec/): languages without an extractor have no test file naming the tool knows, and Rust keeps its tests in such folders.

func InstallLangRules

func InstallLangRules(reg LangRegistry)

InstallLangRules makes reg the process's language registry: the symbol extractors, the language registry (test commands) and the manifest read it. The wiring calls it once at startup, after loading the layered files.

func IsRefDocumentation

func IsRefDocumentation(file string) bool

IsRefDocumentation keeps prose files out of reference results.

func MaskedLineLanguages

func MaskedLineLanguages() string

MaskedLineLanguages names, in registry order, the languages whose references file_refs' approx line matcher masks comments and strings for: the rule languages and PHP. A configuration file (YAML/TOML) keeps its strings visible, so it is not listed.

func MaskedTextLanguages

func MaskedTextLanguages() string

MaskedTextLanguages names the languages the approx note of a file_refs result lists: the masked ones plus the two configuration formats, whose string values stay visible on purpose.

func PinBuiltinExtractors

func PinBuiltinExtractors() (restore func())

PinBuiltinExtractors turns universal-ctags off for the rest of the process and returns the function that restores the previous lookup. The tests of the tool layer use it: which declarations a listing shows must not depend on whether the machine running the tests happens to have ctags installed, and the lookup lives here.

func RefClass

func RefClass(r Ref) string

RefClass is how one match is labelled: the class, plus the qualifier of a selector or call, with the pkg: prefix when the qualifier is an imported package name.

func RefLineText

func RefLineText(line string) string

RefLineText trims a matching line and cuts it at MaxGrepLineBytes, the limit file_grep applies to the lines it shows.

func RefWordRe

func RefWordRe(name string) *regexp.Regexp

RefWordRe compiles the matcher for one name: the name surrounded by characters that cannot be part of an identifier in the supported languages (letters, digits, _ and $; PHP's variables write the name with a leading $, which makes "foo" not match "$foo"). Go's \b is not used because it counts $ and - as boundaries, so $name and foo-name would match.

func ScanBareLineRefs

func ScanBareLineRefs(file string, src []byte, name, qual string, re *regexp.Regexp) ([]Ref, *RefDrops)

ScanBareLineRefs is the fallback for readable text with no extractor. Unlike the registered approximate languages, it deliberately does not mask anything.

func ScanRefs

func ScanRefs(file string, src []byte, name, qual string, re *regexp.Regexp) ([]Ref, bool, *RefDrops, error)

ScanRefs extracts the references of one file: Go by parser (exact), the other languages of the registry by word-bounded text match (approx). A file type the registry does not know is an error; a file without the name yields nothing, which is why the caller filters on the same word-bounded pattern first. qual narrows the result to the Q of a qualified name and dropped is how many occurrences of the name qualified something else.

func SplitRefName

func SplitRefName(raw string) (name, qual string)

SplitRefName splits a possibly qualified name argument: the last dot segment is the name to search and the segment before it the qualifier Q that narrows the result, so "a.b.Run" searches Run with Q=b and "Run" searches it unqualified. A trailing or doubled dot falls back to the text as it is.

func SupportedSymbolLanguages

func SupportedSymbolLanguages() string

SupportedSymbolLanguages names every language of the extractor with its extensions: what a refusal and the tool description tell the model.

func SupportsSymbols

func SupportsSymbols(file string) bool

SupportsSymbols reports whether a file of this name or extension has an extractor. A file of an unknown type is not analysed, but a caller asking for one path is told so instead of getting an empty list.

func TestCommandPattern

func TestCommandPattern() *regexp.Regexp

TestCommandPattern matches the shell commands that run tests, from the language registry; the trace analysis counts and rates them.

Types

type BuiltinRuleFile

type BuiltinRuleFile struct {
	// Name is the file's embedded path, e.g. langrules/python.yaml.
	Name string
	// YAML is the file's raw content, so `suga inspect rules lang --builtin`
	// prints exactly what ships and a rule file can be written from it.
	YAML []byte
}

BuiltinRuleFile is one embedded rule file as the binary carries it.

func BuiltinLangRuleFiles

func BuiltinLangRuleFiles() []BuiltinRuleFile

BuiltinLangRuleFiles returns the embedded language rule files in the order they are read in, so `suga inspect rules lang --builtin` prints exactly what ships and a rule file can be written from them.

type DeclRule

type DeclRule struct {
	// Pattern is a Go regular expression matched against the trimmed line.
	Pattern string `yaml:"pattern"`
	// Kind is the kind reported; KindGroup names the capture group holding it
	// instead (a Java "class|interface|enum|record" line).
	Kind      string `yaml:"kind"`
	KindGroup int    `yaml:"kind_group"`
	// Name is the capture group holding the declaration's name.
	Name int `yaml:"name"`
	// Member limits the rule to a type body: a class member or a nested type,
	// never a statement of a function body.
	Member bool `yaml:"member"`
	// Body tells that the rule opens a type body (class/interface/enum), whose
	// nesting member rules are limited to.
	Body bool `yaml:"body"`
}

DeclRule is one `decls:` entry: a declaration-line pattern and what it reports. It compiles into a braceDecl, the matcher every block style shares.

type EndKeywordRule

type EndKeywordRule struct {
	Open  string `yaml:"open"`
	Close string `yaml:"close"`
}

EndKeywordRule says which lines open a block and which keyword closes it.

type LangManifest

type LangManifest struct {
	Name string   `json:"name"`
	Exts []string `json:"exts"`
	// Source is the layer the rule came from: "builtin" or the file's path.
	Source string `json:"source"`
	// Blocks is the declaration style (Go/PHY/YAML/TOML report their own
	// recogniser instead).
	Blocks string `json:"blocks"`
	// Ctags tells whether universal-ctags can extract the language's files too.
	Ctags bool `json:"ctags"`
	// Approx marks a declaration-line recogniser rather than a parser.
	Approx bool `json:"approx"`
}

LangManifest is one language as `suga inspect manifest` shows it.

type LangRegistry

type LangRegistry struct {
	// Languages are the enabled rules in registry order (built-in first).
	Languages []LangRule
	// Skipped are the files that did not load, with their reason.
	Skipped []LangRuleSkip
	// Warnings are the non-fatal problems of a load (an extension a later rule
	// took from an earlier, differently named one).
	Warnings []string
	// Disabled lists the code languages a rule file switched off.
	Disabled []string
	// contains filtered or unexported fields
}

LangRegistry is the effective language registry: the built-in rules merged with the loaded files, plus what the load skipped.

func ActiveLangRules

func ActiveLangRules() LangRegistry

ActiveLangRules returns the installed registry, or the built-in one when no rule file has been loaded (tests and tools built without wiring).

func BuiltinLangRegistry

func BuiltinLangRegistry() LangRegistry

BuiltinLangRegistry returns the registry of the embedded rules alone.

func DefaultLangRules

func DefaultLangRules() LangRegistry

DefaultLangRules returns the built-in rules (no rule file loaded).

func LoadLangRules

func LoadLangRules(paths ...string) (LangRegistry, []error)

LoadLangRules returns the built-in rules merged with the rule files in order (later files win): a same-name rule replaces an earlier one whole, a new name is appended, enabled: false removes the rule of that name. A missing file is skipped quietly; a file that does not parse or holds a broken rule is reported (and listed in Skipped) and skipped as a whole, like an output-rules file. The returned errors are exactly the skipped files' reasons; Warnings holds the non-fatal extension conflicts.

func (LangRegistry) ManifestLanguages

func (r LangRegistry) ManifestLanguages() []LangManifest

ManifestLanguages lists the effective languages for suga inspect manifest: the code languages with their own recogniser and every enabled rule language.

type LangRule

type LangRule struct {
	Name         string   `yaml:"name"`
	Enabled      *bool    `yaml:"enabled"` // nil = on
	Exts         []string `yaml:"exts"`
	Markers      []string `yaml:"markers"`
	TestCommands string   `yaml:"test_commands"`
	FocusedFlags []string `yaml:"focused_flags"`
	// Ctags is the universal-ctags language: one name for every extension
	// (ctags: Ruby) or one per extension (ctags: {.h: C++}).
	Ctags any `yaml:"ctags"`
	// Syntax is the masking of the language's comments and strings, shared by
	// the declaration recogniser and file_refs.
	Syntax maskSpec `yaml:"syntax"`
	// Blocks is brace, indent or end_keyword; empty = brace.
	Blocks string `yaml:"blocks"`
	// EndKeyword is read when Blocks is end_keyword.
	EndKeyword EndKeywordRule `yaml:"end_keyword"`
	// BodyBraceNextLine accepts the opening brace of a type body on the line
	// after its declaration (the Allman style of C#).
	BodyBraceNextLine bool       `yaml:"body_brace_next_line"`
	Decls             []DeclRule `yaml:"decls"`

	// Source is where the rule came from (builtin, or the loaded file's path);
	// the loader fills it.
	Source string `yaml:"-"`
	// contains filtered or unexported fields
}

LangRule is one language of the rule file. Its compiled forms (the regexps, the mask spec, the ctags map) are filled by compile, the same way an OutputRule and a NudgeRule are.

type LangRuleSkip

type LangRuleSkip struct {
	File string `json:"file"`
	Err  string `json:"err"`
}

LangRuleSkip is one rule file that was skipped, with the reason: a manifest shows it, because a rule file with a typo would otherwise silently not apply.

type Language

type Language struct {
	Name    string   // the language's name, as the prompt and the docs spell it
	Markers []string // project files that identify the language

	// DependencyAPI is this language's clause of the base prompt's
	// dependency-API sentence. It includes how the sentence names the language
	// ("<hint> for Go", "for Java, <hint>") because the sentence's own wording
	// is fixed; the clauses are joined with "; " in Languages() order. It is
	// empty for a language whose dependencies need no command of their own.
	DependencyAPI string

	// TestCommands is a complete regex matching a shell command that runs this
	// language's tests; FocusedFlags are the regex fragments of the flags that
	// limit a run to some tests (they are combined into one shared
	// "(^|\s)(<flags>)(\s|=)" pattern). The trace analysis uses both.
	TestCommands string
	FocusedFlags []string
}

Language is how one programming language's special handling is declared (suga-xt0o): one file per language (lang_go.go, lang_java.go, ...), the same way the LLM layer keeps one file per provider (pkg/agentcore/llm/compat_*.go). A language declares where its dependency sources live on this machine, how the model reads a dependency's API, which shell commands run its tests and which project files identify it.

The declarations feed three consumers:

  • DependencyRoots: dependencyRoots adds the local caches whose files the read-only file tools may read.
  • the base prompt: DependencyAPI is one clause of the dependency-API sentence (internal/wiring/prompt.go joins them into one line). The wording is part of the provider's cached prompt prefix, so the clause of an existing language changes only together with its test.
  • the trace analysis (internal/personal/analyze.go): TestCommands and FocusedFlags recognise test runs and runs limited to some tests.

Markers (go.mod, pom.xml, ...) are declared but not used yet: the base prompt carries the clause of every language today.

func Languages

func Languages() []Language

languages is the registry, in the order the dependency roots appear in the environment prompt and the prompt clauses are read: Go, Rust, Java, JS, Python, PHP. That order is the historical one (the roots were detected in it before the split, suga-xt0o), so both the read root list and the prompt stay byte-identical; a new language is appended at the end and the existing ones stay where they are (the prompt itself does not change: PHP declares no DependencyAPI clause, so the sentence reads as before).

It is composed from the code languages (Go, Rust, PHP) and the rule languages (Java, JavaScript/TypeScript, Python and the languages a rule file adds), so a lang-rules.yaml can tune a language's test commands without a code change.

type Ref

type Ref struct {
	File  string // as the caller names the file: relative to the workspace, absolute under a read root
	Line  int    // 1-based line of the occurrence
	Class string // one of RefDef, RefCall, RefSel, RefRef
	// Qualifier is the X of an X.Name occurrence (call/sel): a package name, a
	// value, a field or a receiver. Empty for def/ref.
	Qualifier string
	// Pkg marks a qualifier that the same file imports as a package name, so
	// runtime.ReadOnly (a package symbol) is told from cfg.ReadOnly (a field).
	Pkg bool
	// Text is the trimmed source line, at most MaxGrepLineBytes like file_grep.
	Text string
}

Ref is one occurrence of a searched name in a source file.

func ScanGoRefs

func ScanGoRefs(file string, src []byte, name string) ([]Ref, error)

ScanGoRefs returns every occurrence of name in one Go file, classified by go/parser + go/ast without type checking (parser.SkipObjectResolution, the same minimal parse the declaration extractor uses). Occurrences inside comments and string literals are not identifiers, so they never match. A file that does not parse returns its error to the caller.

func ScanLineRefs

func ScanLineRefs(file string, src []byte, name string) []Ref

ScanLineRefs returns the approx references to name in one file: one Ref per matching line, class RefRef (a text match cannot tell a definition from a use). Comments and string literals are masked first (maskSpans, then maskInline), so a name inside them is no reference. The masking is the approximation: an interpolation in a template string is masked with the rest of the literal, so it is not reported.

type RefDrops

type RefDrops struct {
	// contains filtered or unexported fields
}

RefDrops is what a qualified file_refs search left out: the count of occurrences by the qualifier text they had ("child" for child.Run, "pkg:exec" for exec.Run through an import, "" for a bare use or an approximate text match), and the occurrences through variables, whose type the textual filter cannot tell.

func NewRefDrops

func NewRefDrops() *RefDrops

func (*RefDrops) Describe

func (d *RefDrops) Describe() string

Describe names the dropped variable qualifiers (sorted, with counts) and sums up the imported packages and the unqualified uses: ` (variables: child 1, cmd 3, t 40; 5 through imported packages; 2 unqualified or text matches)`. Empty when nothing was dropped.

func (*RefDrops) Merge

func (d *RefDrops) Merge(other *RefDrops)

Merge adds the drops of one file to the totals of a search.

func (*RefDrops) Rare

func (d *RefDrops) Rare() ([]Ref, int)

Rare returns the dropped occurrences worth a line of their own, in path and line order and capped, plus how many were left out by the cap: the Go uses without a qualifier (a call inside the defining package needs none) and the uses through a variable qualifier that occurs at most RareDropUses times in the search. The model reads result lines, not trailing notes: a *Runner held in a variable called child, or config's own ReadModelSettings("") under name appconfig.ReadModelSettings, has to appear as a line to be noticed.

func (*RefDrops) Total

func (d *RefDrops) Total() int

Total is how many occurrences were dropped.

type SourceLines

type SourceLines struct{ Lines []string }

SourceLines is one file's lines, split once so a signature lookup per symbol is an index. Line numbers are 1-based; "\r\n" ends are trimmed like the file tools do.

func NewSourceLines

func NewSourceLines(src []byte) SourceLines

func (SourceLines) At

func (s SourceLines) At(n int) string

At returns the trimmed line n, "" when the number is out of range.

type Symbol

type Symbol struct {
	File      string // as the caller names the file: relative to the workspace, absolute under a read root
	Line      int    // 1-based line of the declaration
	Kind      string // one of SymbolKinds (a language-specific kind when ctags reports one the tool does not know)
	Name      string
	Signature string // the declaration's first line, trimmed
}

Symbol is one declaration of a source file: where it is, what its language calls it, its name, and the trimmed text of its declaration line (so a Go method shows its receiver and a Java method its parameters).

type SymbolSet

type SymbolSet struct {
	Symbols []Symbol
	// Approx marks a lightweight, line-based recognition instead of a parser:
	// the names and kinds are close, but they are not proof, so the tool says
	// so and a file_grep confirms a name that matters.
	Approx bool
	// Source names what did the extraction; the tests assert it.
	Source string
	// Notes are extra lines the extractor wants the tool to show besides its
	// approx marker: what its own caps left out (YAML/TOML depth and key count),
	// which the tool alone cannot know. file_symbols and file_read's outline
	// print them after the declarations.
	Notes []string
}

SymbolSet is the result of extracting one file's declarations.

func ExtractSymbols

func ExtractSymbols(file string, src []byte) (SymbolSet, error)

ExtractSymbols returns the declarations of one source file: file is both how the results name it and the path universal-ctags parses when it is installed, src is the file's content. A file type no source covers is refused with the list of supported languages.

func ExtractSymbolsAt

func ExtractSymbolsAt(file, onDisk string, src []byte) (SymbolSet, error)

ExtractSymbolsAt is ExtractSymbols for a file whose display name is not a usable argument of an external tool (a path relative to the workspace): file names the results, onDisk is where the content can be read again.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL