Documentation
¶
Index ¶
- Constants
- Variables
- func BareRefClass(line, name string) string
- func DeclLineLanguages() string
- func FocusedTestPattern() *regexp.Regexp
- func InTestDir(rel string) bool
- func InstallLangRules(reg LangRegistry)
- func IsRefDocumentation(file string) bool
- func MaskedLineLanguages() string
- func MaskedTextLanguages() string
- func PinBuiltinExtractors() (restore func())
- func RefClass(r Ref) string
- func RefLineText(line string) string
- func RefWordRe(name string) *regexp.Regexp
- func ScanBareLineRefs(file string, src []byte, name, qual string, re *regexp.Regexp) ([]Ref, *RefDrops)
- func ScanRefs(file string, src []byte, name, qual string, re *regexp.Regexp) ([]Ref, bool, *RefDrops, error)
- func SplitRefName(raw string) (name, qual string)
- func SupportedSymbolLanguages() string
- func SupportsSymbols(file string) bool
- func TestCommandPattern() *regexp.Regexp
- type BuiltinRuleFile
- type DeclRule
- type EndKeywordRule
- type LangManifest
- type LangRegistry
- type LangRule
- type LangRuleSkip
- type Language
- type Ref
- type RefDrops
- type SourceLines
- type Symbol
- type SymbolSet
Constants ¶
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.
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.
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 )
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.
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.
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 )
const RuleSourceBuiltin = "builtin"
RuleSourceBuiltin marks a rule that ships with the binary.
const RuleSourceCode = "code"
RuleSourceCode marks a language whose extractor stays in Go code.
Variables ¶
var SymbolKinds = []string{SymbolFunc, SymbolMethod, SymbolType, SymbolConst, SymbolVar, SymbolClass, SymbolInterface, SymbolEnum, SymbolRecord, SymbolTrait, SymbolSection, SymbolKey}
SymbolKinds is the whole kind vocabulary, in the order the messages list it.
Functions ¶
func BareRefClass ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
RefLineText trims a matching line and cuts it at MaxGrepLineBytes, the limit file_grep applies to the lines it shows.
func RefWordRe ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 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: 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 ¶
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 ¶
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 ¶
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 ¶
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) Rare ¶
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.
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 ¶
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 ¶
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.