Documentation
¶
Overview ¶
Package codeanalysis provides high-level code analysis capabilities for the HelixKnowledge system. It scans project directories, extracts patterns and imports using tree-sitter (or regex fallback), and maps discovered patterns to existing skills in the knowledge graph.
Package codeanalysis provides tree-sitter integration for parsing codebases and extracting patterns. The tree-sitter parser is used when CGO is available; otherwise, it falls back to regex-based parsing.
treesitter_native.go provides the CGO-backed native tree-sitter parser implementation. When CGO is enabled and tree-sitter grammars are available, this file's init() replaces the default stub function pointers in treesitter.go with real implementations.
Supported languages with native grammars: go, python, java, javascript, c, cpp, rust, csharp. Languages without Go bindings (kotlin, typescript) continue to use the regex fallback.
Index ¶
- Variables
- func ValidateProjectPath(projectPath, allowedRoot string) (string, error)
- type AnalysisResult
- type Analyzer
- func (a *Analyzer) AnalyzeProject(ctx context.Context, projectPath string) (*AnalysisResult, error)
- func (a *Analyzer) DetectPatterns(ctx context.Context, filePath string, content []byte, language string) ([]Pattern, error)
- func (a *Analyzer) ExtractImports(ctx context.Context, filePath string, content []byte) ([]Import, error)
- func (a *Analyzer) MapToSkills(ctx context.Context, patterns []Pattern, store *skill.Store) ([]SkillMapping, error)
- func (a *Analyzer) PatternsToEvidence(patterns []Pattern, skillID uuid.UUID, projectPath string) []models.Evidence
- type Class
- type FallbackParse
- type Fidelity
- type Function
- type Import
- type Pattern
- type RegexParser
- type SkillMapping
- type TSNode
- type Tree
- type TreeSitterParser
- func (p *TreeSitterParser) ExtractClasses(tree *Tree) ([]Class, error)
- func (p *TreeSitterParser) ExtractFunctions(tree *Tree) ([]Function, error)
- func (p *TreeSitterParser) ExtractImports(tree *Tree, language string) ([]Import, error)
- func (p *TreeSitterParser) GetSupportedLanguages() []string
- func (p *TreeSitterParser) IsLanguageSupported(language string) bool
- func (p *TreeSitterParser) Parse(content []byte, language string) (*Tree, error)
Constants ¶
This section is empty.
Variables ¶
var ErrNoPatternsForLanguage = errors.New("no regex patterns compiled for language (unsupported or misconfigured)")
ErrNoPatternsForLanguage is returned when the regex-based parser has no compiled patterns for a given language. Before this sentinel existed (G12, §2.3), an unsupported language silently returned an empty FallbackParse, making a Kotlin/C# file indistinguishable from a genuinely-empty file.
Functions ¶
func ValidateProjectPath ¶
ValidateProjectPath canonicalizes projectPath and verifies it resolves strictly inside allowedRoot. It is FAIL-CLOSED: an unset allowedRoot, an empty projectPath, any resolution error (including a path that does not exist), or a canonical path that escapes allowedRoot's boundary all result in a rejection -- never a walk.
On success it returns the fully canonicalized (absolute, symlink-resolved, cleaned) form of projectPath, which callers should use in place of the raw, attacker-influenced input for any subsequent filesystem operation.
Canonicalization order:
- filepath.Abs + filepath.Clean on both allowedRoot and projectPath, so relative traversal segments ("../..") are collapsed before comparison.
- filepath.EvalSymlinks on both, so a symlink planted INSIDE allowedRoot that resolves OUTSIDE it (or vice versa) cannot be used to smuggle an escape past a purely lexical check.
- A path-BOUNDARY comparison (isWithinRoot) of the two canonical forms -- never a raw strings.HasPrefix, which would incorrectly accept a sibling directory such as "/rootEVIL" for an allowedRoot of "/root".
Types ¶
type AnalysisResult ¶
type AnalysisResult struct {
ProjectPath string `json:"project_path"`
Languages map[string]int `json:"languages"` // language -> file count
Imports []Import `json:"imports"`
Patterns []Pattern `json:"patterns"`
Mappings []SkillMapping `json:"mappings"`
NewPatterns []Pattern `json:"new_patterns"` // patterns not matching any existing skill
}
AnalysisResult captures the complete analysis of a project.
func (*AnalysisResult) MarshalJSON ¶
func (r *AnalysisResult) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling for AnalysisResult.
type Analyzer ¶
type Analyzer struct {
// contains filtered or unexported fields
}
Analyzer parses codebases and extracts architectural patterns and imports.
func NewAnalyzer ¶
func NewAnalyzer(cfg config.CodeAnalysisConfig, logger *zap.Logger) *Analyzer
NewAnalyzer creates a new code analyzer.
func (*Analyzer) AnalyzeProject ¶
AnalyzeProject scans a project directory and extracts patterns, imports, and language statistics. It maps discovered patterns to existing skills and identifies new patterns that don't match any known skill.
projectPath is validated against a.cfg.AllowedRoot (§G31 path-traversal / LFI guard) BEFORE any filesystem walk starts -- fail-closed, so an unconfigured allowed root or an escaping path is rejected here rather than walked. This is defense-in-depth alongside the caller-side guard in internal/mcp's learn_from_project handler: whatever future caller reaches this method, the walk itself can never be pointed outside the allowlisted root.
func (*Analyzer) DetectPatterns ¶
func (a *Analyzer) DetectPatterns(ctx context.Context, filePath string, content []byte, language string) ([]Pattern, error)
DetectPatterns identifies architectural patterns in a source file. It combines tree-sitter AST analysis with regex-based heuristic detection.
func (*Analyzer) ExtractImports ¶
func (a *Analyzer) ExtractImports(ctx context.Context, filePath string, content []byte) ([]Import, error)
ExtractImports finds all imports in a source file. This is a convenience method that parses the file and extracts imports in one step.
func (*Analyzer) MapToSkills ¶
func (a *Analyzer) MapToSkills(ctx context.Context, patterns []Pattern, store *skill.Store) ([]SkillMapping, error)
MapToSkills maps detected patterns and imports to existing skills in the knowledge graph. It returns a list of mappings linking patterns to skills.
type Class ¶
type Class struct {
Name string
Type string // "class", "struct", "interface", "trait"
File string
Line int
Language string
Methods []Function
}
Class represents a class, struct, or type definition.
type FallbackParse ¶
FallbackParse holds results from regex-based parsing.
type Fidelity ¶
type Fidelity string
Fidelity describes the parser path that produced a parse result.
const ( // FidelityNative indicates parsing was performed by the CGO-backed // tree-sitter native parser (real AST, accurate). FidelityNative Fidelity = "native" // FidelityRegexFallback indicates parsing was performed by the regex // fallback parser (heuristic, reduced accuracy). FidelityRegexFallback Fidelity = "regex-fallback" )
type Function ¶
type Function struct {
Name string
Signature string
Body string
File string
Line int
Language string
IsExported bool
}
Function represents a function or method extracted from source code.
type Import ¶
type Import struct {
Path string `json:"path"`
File string `json:"file"`
Line int `json:"line"`
Language string `json:"language"`
}
Import represents a single import/include statement found in source code.
type Pattern ¶
type Pattern struct {
Type string `json:"type"` // e.g., "mvvm", "repository", "dependency-injection"
File string `json:"file"`
Line int `json:"line"`
Snippet string `json:"snippet"`
Confidence float64 `json:"confidence"` // 0.0 to 1.0
}
Pattern represents an architectural pattern detected in source code.
type RegexParser ¶
type RegexParser struct {
// contains filtered or unexported fields
}
RegexParser provides language-aware regex-based code parsing.
func (*RegexParser) Parse ¶
func (p *RegexParser) Parse(content []byte) *FallbackParse
Parse extracts code structure using regex patterns.
type SkillMapping ¶
type SkillMapping struct {
Pattern Pattern `json:"pattern"`
SkillID uuid.UUID `json:"skill_id"`
SkillName string `json:"skill_name"`
Score float64 `json:"score"` // similarity score
}
SkillMapping links a detected pattern to an existing skill in the graph.
type Tree ¶
type Tree struct {
Language string
Content []byte
// Fidelity indicates the parser path used: "native" (CGO tree-sitter)
// or "regex-fallback" (§2.3, G12). Never left blank for a successfully
// parsed file.
Fidelity Fidelity
// When using native parsing, Root holds the tree-sitter root node.
// When using fallback, Parsed holds regex-extracted entities.
Root *TSNode
Parsed *FallbackParse
}
Tree represents an abstract syntax tree produced by tree-sitter.
type TreeSitterParser ¶
type TreeSitterParser struct {
// contains filtered or unexported fields
}
TreeSitterParser wraps tree-sitter Go bindings for parsing source code. When CGO is unavailable, it transparently falls back to regex-based parsing.
func NewTreeSitterParser ¶
func NewTreeSitterParser() (*TreeSitterParser, error)
NewTreeSitterParser creates a new tree-sitter parser. It attempts to initialize native parsers for supported languages, falling back to regex-based parsers for any that fail.
func (*TreeSitterParser) ExtractClasses ¶
func (p *TreeSitterParser) ExtractClasses(tree *Tree) ([]Class, error)
ExtractClasses finds all class/struct/type definitions in a parsed source file.
func (*TreeSitterParser) ExtractFunctions ¶
func (p *TreeSitterParser) ExtractFunctions(tree *Tree) ([]Function, error)
ExtractFunctions finds all function/method definitions in a parsed source file.
func (*TreeSitterParser) ExtractImports ¶
func (p *TreeSitterParser) ExtractImports(tree *Tree, language string) ([]Import, error)
ExtractImports finds all imports in a parsed source file.
func (*TreeSitterParser) GetSupportedLanguages ¶
func (p *TreeSitterParser) GetSupportedLanguages() []string
GetSupportedLanguages returns the list of languages the parser supports.
func (*TreeSitterParser) IsLanguageSupported ¶
func (p *TreeSitterParser) IsLanguageSupported(language string) bool
IsLanguageSupported checks if a language can be parsed.
func (*TreeSitterParser) Parse ¶
func (p *TreeSitterParser) Parse(content []byte, language string) (*Tree, error)
Parse parses source code content and returns an AST representation. It uses the native tree-sitter parser when available, otherwise falls back to regex-based parsing. Fidelity is always set for a successfully parsed result.
Source Files