graphfrag

type CallFrame struct {
	Component ComponentKey
	Function  string
}

type ComponentKey struct {
	Purl    string
	Version string
}

type CryptoOperation struct {
	Function  string
	FindingID string
	RuleID    string
	Symbol    string
}

type DependencyGraph map[ComponentKey][]ComponentKey

type ErrMissingFragment struct {
	Components []ComponentKey
}

type ExternalCall struct {
	Caller          string
	TargetSignature string

	// Resolution classifies how the producer resolved TargetSignature. The zero
	// value (ResolutionUnknown) is fail-closed: the stitcher will not traverse it.
	Resolution ResolutionKind

	// DeclaredType is the static/interface type observed at the call site (e.g.
	// the interface whose method was dispatched). Provenance plus part of the
	// dispatch-group identity used to detect ambiguous interface dispatch.
	DeclaredType string

	// MethodName and Arity identify the invoked method independently of the
	// resolved target, so sibling candidates of one ambiguous call site can be
	// grouped together.
	MethodName string
	Arity      int

	// CallSite is the source line of the call expression. Together with Caller,
	// MethodName, and Arity it discriminates distinct call sites that happen to
	// share a method name within the same caller.
	CallSite int
}

type FindingChain struct {
	FindingID string
	RuleID    string
	Symbol    string
	Frames    []CallFrame

	// Confidence is the weakest-link confidence of the traversed edges. Under
	// the default policy this is always ConfidenceHigh.
	Confidence string
}

type Fragment struct {
	Component ComponentKey
	Module    string

	Functions        []Function
	InternalEdges    []InternalEdge
	ExternalCalls    []ExternalCall
	CryptoOperations []CryptoOperation
}

type Function struct {
	Signature string
	FilePath  string
}

type GraphFragmentCryptoOp struct {
	FunctionKey string `json:"function_key,omitempty"`
	FindingID   string `json:"finding_id,omitempty"`
	RuleID      string `json:"rule_id,omitempty"`
	Symbol      string `json:"symbol,omitempty"`
	Expression  string `json:"expression,omitempty"`
	FilePath    string `json:"file_path,omitempty"`
	StartLine   int    `json:"start_line,omitempty"`
	EndLine     int    `json:"end_line,omitempty"`
}

type GraphFragmentEdge struct {
	CallerKey    string `json:"caller_key"`
	CalleeKey    string `json:"callee_key"`
	Line         int    `json:"line,omitempty"`
	Resolution   string `json:"resolution"`
	DeclaredType string `json:"declared_type,omitempty"`
	MethodName   string `json:"method_name,omitempty"`
	Arity        int    `json:"arity,omitempty"`
}

type GraphFragmentExport struct {
	SchemaVersion     string                    `json:"schema_version"`
	ScanMetadata      GraphFragmentScanMetadata `json:"scan_metadata"`
	Functions         []GraphFragmentFunction   `json:"functions"`
	InternalEdges     []GraphFragmentEdge       `json:"internal_edges,omitempty"`
	ExternalCalls     []GraphFragmentExternal   `json:"external_calls,omitempty"`
	CryptoAnnotations []GraphFragmentCryptoOp   `json:"crypto_annotations,omitempty"`
}

type GraphFragmentExternal struct {
	CallerKey          string `json:"caller_key"`
	TargetKey          string `json:"target_key"`
	TargetFunctionName string `json:"target_function_name,omitempty"`
	Raw                string `json:"raw,omitempty"`
	Line               int    `json:"line,omitempty"`
	Resolution         string `json:"resolution"`
	DeclaredType       string `json:"declared_type,omitempty"`
	MethodName         string `json:"method_name,omitempty"`
	Arity              int    `json:"arity,omitempty"`
}

type GraphFragmentFunction struct {
	Key                string          `json:"key"`
	FunctionName       string          `json:"function_name"`
	CanonicalSignature string          `json:"canonical_signature,omitempty"`
	Package            string          `json:"package,omitempty"`
	Type               string          `json:"type,omitempty"`
	Name               string          `json:"name,omitempty"`
	FilePath           string          `json:"file_path,omitempty"`
	StartLine          int             `json:"start_line,omitempty"`
	EndLine            int             `json:"end_line,omitempty"`
	ReturnType         string          `json:"return_type,omitempty"`
	ParameterTypes     []string        `json:"parameter_types,omitempty"`
	Visibility         string          `json:"visibility,omitempty"`
	OwnerVisibility    string          `json:"owner_visibility,omitempty"`
	InferredReturn     json.RawMessage `json:"-"`
}

type GraphFragmentScanMetadata struct {
	Ecosystem     string `json:"ecosystem,omitempty"`
	RootModule    string `json:"root_module,omitempty"`
	ToolName      string `json:"tool_name,omitempty"`
	ToolVersion   string `json:"tool_version,omitempty"`
	RulesVersion  string `json:"rules_version,omitempty"`
	ExportedAt    string `json:"exported_at"`
	FunctionCount int    `json:"function_count"`
	InternalEdges int    `json:"internal_edge_count"`
	ExternalCalls int    `json:"external_call_count"`
	CryptoOps     int    `json:"crypto_operation_count"`
}

type InternalEdge struct {
	Caller string
	Callee string

	// Resolution classifies how the producer resolved Callee. Zero value
	// (ResolutionUnknown) is fail-closed.
	Resolution ResolutionKind

	// DeclaredType, MethodName, Arity, CallSite mirror ExternalCall and identify
	// the dispatched method / call site for ambiguity grouping.
	DeclaredType string
	MethodName   string
	Arity        int
	CallSite     int
}

type ResolutionKind string

type Result struct {
	Chains []FindingChain

	// Suppressed records call edges the policy refused to traverse. It is the
	// audit trail for fail-closed decisions and the data source for a future
	// opt-in "show me the uncertain paths too" mode. It never affects Chains.
	Suppressed []SuppressedEdge
}

type SuppressedEdge struct {
	Caller     CallFrame
	MethodName string
	Arity      int
	Reason     string
	Candidates []ComponentKey
}