Documentation
¶
Overview ¶
Package ruleengine is codefit's own matcher for a subset of the Semgrep rule format (PRD section 17). Deterministic detection rules are written as declarative YAML (the de-facto standard, with a large community corpus) and matched in pure Go over the provider's AST — the OCaml Semgrep/OpenGrep engine is NOT embedded, which would break the single, CGO-free binary.
Supported operators (the core subset): pattern, pattern-either, patterns, pattern-not, pattern-inside, metavariables ($VAR), metavariable-regex. Deliberately NOT supported: taint mode and pattern-sources/sinks/sanitizers — their role is covered by the agent reasoning over mapped surface.
Status: SKELETON. This declares the rule shape (Rule) and the matcher contract (Engine). The matcher itself is implemented in Fase 1; the AST argument is abstract (any) until the per-language AST adapter is designed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Match ¶
Match runs the compiled rules over the tree rooted at root and returns the findings, located by file and line. file is the project-relative path.
func Matches ¶
Matches reports whether the (already-parsed) pattern node matches the code node structurally, returning the metavariable bindings (name -> matched source text). It is the core of the matcher and is exported so each operator can be tested against real trees.
Matching is purely structural — no ellipsis (PRD §17 subset): a metavariable matches any node (and binds, consistently across repeats); otherwise node types must be equal and named children must match pairwise; leaves compare by text.
Types ¶
type CompiledRule ¶
type CompiledRule struct {
// contains filtered or unexported fields
}
CompiledRule is a Rule whose pattern strings have been parsed to syntax.Node (once, at load time) and whose metavariable regexes are compiled. The ruleengine never parses source itself — Compile receives a parse function from the active provider, so the engine stays parser-agnostic.
type Engine ¶
type Engine interface {
// Match runs the rules against a parsed AST and returns the findings.
Match(rules []Rule, ast any) ([]findings.Finding, error)
}
Engine matches rules against a parsed file and emits deterministic findings.
Skeleton: the ast argument is intentionally abstract (any) until the per-language AST adapter is designed in Fase 1. No implementation yet.
type Rule ¶
type Rule struct {
ID string `yaml:"id"`
Message string `yaml:"message"`
Suggestion string `yaml:"suggestion"`
Severity findings.Severity `yaml:"severity"`
Dimension findings.Dimension `yaml:"dimension"`
// Operators (core subset). Exactly the set codefit's matcher supports.
Pattern string `yaml:"pattern,omitempty"`
PatternEither []string `yaml:"pattern-either,omitempty"`
Patterns []string `yaml:"patterns,omitempty"`
PatternNot string `yaml:"pattern-not,omitempty"`
PatternInside string `yaml:"pattern-inside,omitempty"`
MetavariableRegex map[string]string `yaml:"metavariable-regex,omitempty"`
}
Rule is a deterministic detection rule in the supported Semgrep-format subset (PRD section 17). A rule carries its finding metadata plus one or more pattern operators; the operators are mutually composable (patterns = AND of its members, PatternEither = OR, etc.).
func LoadFS ¶
LoadFS reads and validates every *.yaml rule file under dir in fsys and returns the rules in a stable, file-sorted order. fsys is supplied by the caller (the embedded rules/ FS in production, an in-memory FS in tests), so the engine never reaches the real filesystem itself.
Validation is strict and located: a malformed file or a structurally invalid rule fails with an error naming the file (and the rule id when known), so a broken rule can never enter the engine silently — a silent rule is a silent vulnerability.
Source Files