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: BUILT (Fase 1). The rule shape (Rule), the YAML loader, and the matcher itself (Compile, Match, Matches) are implemented, and the TypeScript provider runs its deterministic security rules through them. Note the shape: the matcher is package-level FUNCTIONS over syntax.Node, not the Engine interface — Engine is a declared contract that nothing implements today, kept for the per-language adapter it was drawn for. Do not read it as the entry point.
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.
NOT IMPLEMENTED by anything today: the working matcher is the package-level Compile/Match pair over syntax.Node. This interface is kept for the per-language AST adapter it was drawn for, which is why its ast argument is still abstract (any).
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