Documentation
¶
Overview ¶
Package contracts provides the JCA/JCE knowledge base (KB) loader and types for the callgraph inference engine. It defines YAML-based contract definitions that map method signatures to their inferred return types.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Condition ¶
type Condition struct {
ArgIndex int
ArgValueIn []string // matches if resolved literal is one of these
}
Condition constrains when this contract applies based on an argument value.
type Contract ¶
type Contract struct {
Method string
Arity int
When *Condition // nil = unconditional contract
Return ContractReturn
SourceLibrary string // populated by Load() from the v2 YAML library.name field
}
Contract describes a single KB entry mapping a method call to an inferred return type.
type ContractReturn ¶
ContractReturn holds the inferred return type and confidence for a contract.
type KnowledgeBase ¶
type KnowledgeBase struct {
SchemaVersion string
Ecosystem string
// Library holds the library metadata from the v2 YAML library: block.
// Nil when this KB is the result of Merge() over >= 2 distinct libraries.
Library *Library
// Contracts is indexed by qualified-method-arity key:
// "<package>.<Type>.<method>#<arity>" e.g. "javax.crypto.Cipher.unwrap#3".
// For constructors: "<package>.<Type>.<init>#<arity>".
// Multiple contracts can share a key when argument-conditional.
Contracts map[string][]Contract
// Hierarchy maps a child FQN to its direct parent FQNs. Used for LUB.
Hierarchy map[string][]string
}
KnowledgeBase is the loaded, indexed JCA/JCE contract set.
func Load ¶
func Load(data []byte) (*KnowledgeBase, error)
Load parses and validates a YAML knowledge base payload. Returns a validated, indexed KnowledgeBase or an error.
func LoadEmbedded ¶
func LoadEmbedded(ecosystem string) (*KnowledgeBase, error)
LoadEmbedded discovers and loads all *.yaml files in the given ecosystem directory under the embedded contracts FS, validates each, and returns the merged KnowledgeBase. Duplicate library.name values across files are detected here because LoadEmbedded has access to file paths for the diagnostic.
Returns an empty *KnowledgeBase (nil error) if the ecosystem is unknown or the directory has no YAML files. Returns an error if any file cannot be read, fails validation, or if two files declare the same library.name.
func Merge ¶
func Merge(kbs ...*KnowledgeBase) (*KnowledgeBase, error)
Merge combines multiple per-library KnowledgeBases into a single merged KB, applying conflict detection rules. Returns an error if any conflict rule is violated. The result KB has Library = nil (it represents a merger of N libraries; no single library identifies it).
Conflict rules:
- Same key + identical contract → idempotent (keep one, no error).
- Same key + same condition + DIFFERENT return → HARD ERROR (names both libs).
- Hierarchy child→[A] in both → idempotent.
- Hierarchy child→[A] vs child→[B] → HARD ERROR.
- Hierarchy child→[A] vs child→[A,B] → UNION (output is the larger set).
func (*KnowledgeBase) ContractsFor ¶
func (kb *KnowledgeBase) ContractsFor(method string, arity int) []Contract
ContractsFor returns all contracts for the given method FQN and arity.
Source Files