evidence

Documentation

Overview

Package evidence is a thin facade over scanner.File + the wired type resolvers, exposing only the structured questions a rule should ask.

Rule bodies that work through Evidence get receiver-typing, callee-name, and argument navigation through one API. Direct *scanner.File access (and the substring-on-source-text patterns it invites) stays available in the rules package today, but new rules should prefer this layer so the cheap-receiver-typing path is shared and memoized.

Index

• type Call
• type Evidence
  • func From(ctx *api.Context) *Evidence
  • func (e *Evidence) Call(idx uint32) *Call
  • func (e *Evidence) File() *scanner.File
  • func (e *Evidence) ResolveCalleeFQN(c *Call) (fqn string, source OwnerSource)
  • func (e *Evidence) ResolveOwner(c *Call) (fqn string, source OwnerSource)
• type OwnerSource

Types

type Call

type Call struct {
	Idx      uint32 // FlatNode index of the call site
	Callee   string // simple callee name; "" if it could not be extracted
	Receiver string // syntactic receiver (simple identifier or dotted chain); "" if unqualified

	// ReceiverIdx is the FlatNode index of the receiver expression — the
	// part before the trailing navigation_suffix. Zero when the call has
	// no receiver. Useful for chained calls: pass it to Evidence.Call to
	// descend into the inner call (e.g. unwrap Runtime.getRuntime() inside
	// Runtime.getRuntime().exec(...)).
	ReceiverIdx uint32
}

Call is a structural view over a call_expression / method_invocation node. Build via Evidence.Call. Receiver is the syntactic receiver name (or dotted chain) — empty for unqualified calls. Use ResolveOwner to get the resolved FQN of the receiver type.

type Evidence

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

Evidence wraps a Context's read-only inputs with cached per-file lookups. One Evidence per rule invocation is fine — the underlying caches live on the file, not on the Evidence value.

func From

func From(ctx *api.Context) *Evidence

From wraps the rule's Context. Returns nil only when ctx itself is nil.

func (*Evidence) Call

func (e *Evidence) Call(idx uint32) *Call

Call wraps the call site at the given flat index. Returns nil if the node is not a call_expression / method_invocation.

func (*Evidence) File

func (e *Evidence) File() *scanner.File

File returns the underlying file. Provided for emit-position math (line/col lookups) — rules should not use it to read source text.

func (*Evidence) ResolveCalleeFQN

func (e *Evidence) ResolveCalleeFQN(c *Call) (fqn string, source OwnerSource)

ResolveCalleeFQN returns the FQN of an unqualified call's callee using the file's import table. Useful for constructor-style patterns like `SimpleSQLiteQuery(...)` or `ProcessBuilder(...)` where the callee is the type name and the rule wants to verify which FQN it refers to.

Returns ("", OwnerUnknown) when the callee is qualified (Foo.bar()), not import-resolvable, or empty. For qualified calls, use ResolveOwner against the receiver instead.

func (*Evidence) ResolveOwner

func (e *Evidence) ResolveOwner(c *Call) (fqn string, source OwnerSource)

ResolveOwner returns the FQN of the call's receiver type and the backend that proved it. Returns ("", OwnerUnknown) when no backend could prove an answer — rules that need receiver proof should bail out on that case rather than falling back to substring matching.

Backends are tried in cheap-to-expensive order:

1. ImportEvidence: receiver is a type-name (`Foo.bar()`) named in the file's imports. Free.
2. Resolver: source-level Kotlin scope/import resolution (only when the rule declared NeedsResolver, otherwise nil).
3. JavaSource: walk the enclosing Java method/class for a parameter, field, or local declaration of the receiver name, then resolve via JavaFacts. Java-only; no-op for Kotlin.

Per-call results are memoized for the lifetime of this Evidence.

type OwnerSource

type OwnerSource uint8

OwnerSource records which backend proved a call's owner type. OwnerUnknown means no backend could prove it — rules requiring receiver proof must bail out on this value.

const (
	OwnerUnknown OwnerSource = iota
	// OwnerImportEvidence: receiver was a type-name receiver (e.g.
	// `Foo.bar()`) and the file's import table named the FQN.
	OwnerImportEvidence
	// OwnerResolver: the in-process source resolver returned an FQN
	// (Kotlin scopes, parameter types, property declarations).
	OwnerResolver
	// OwnerJavaSource: the Java AST + JavaFacts produced an FQN
	// from a parameter, field, or local declaration in scope.
	OwnerJavaSource
)