analyzer

type AnalyzeRequest struct {
	AnalyzerContext  AnalyzerContext
	ExecutionContext ExecutionContext
}

type AnalyzedBatchOperation interface {
	Annotated
	ChainSelector() uint64
	Calls() AnalyzedCalls
}

type AnalyzedBatchOperations []AnalyzedBatchOperation

type AnalyzedCall interface {
	Annotated
	To() string
	Name() string
	Inputs() AnalyzedParameters
	Outputs() AnalyzedParameters
	Data() []byte
	ContractType() string
	ContractVersion() string
	AdditionalFields() map[string]any
}

type AnalyzedCalls []AnalyzedCall

type AnalyzedParameter interface {
	Annotated
	Name() string
	Type() string
	Value() any
}

type AnalyzedParameters []AnalyzedParameter

type AnalyzedProposal interface {
	Annotated
	BatchOperations() AnalyzedBatchOperations
}

type AnalyzerContext interface {
	// Proposal returns the current proposal-level context.
	// This is primarily meaningful for ProposalAnalyzer execution.
	Proposal() AnalyzedProposal
	// BatchOperation returns the current batch operation context.
	// This is primarily meaningful for ProposalAnalyzer and BatchOperationAnalyzer execution.
	BatchOperation() AnalyzedBatchOperation
	// Call returns the current call-level context.
	// This is primarily meaningful for ProposalAnalyzer, BatchOperationAnalyzer and CallAnalyzer execution.
	Call() AnalyzedCall

	// GetAnnotationsFrom returns annotations from a specific analyzer.
	// This is useful for accessing results from dependency analyzers.
	// Returns empty slice if the analyzer ID is not found or no annotations exist.
	GetAnnotationsFrom(analyzerID string) Annotations
}

type Annotated interface {
	// AddAnnotations mutates the underlying analyzed object by appending annotations.
	// Implementations are expected to be used by a single analysis pipeline and are
	// not required to provide internal synchronization for concurrent mutation.
	AddAnnotations(annotations ...Annotation)
	Annotations() Annotations
}

type Annotation interface {
	Name() string
	Type() string
	Value() any
}

type Annotations []Annotation

type BaseAnalyzer interface {
	ID() string
	// Dependencies returns the IDs of analyzers that must run before this analyzer.
	//
	// The returned strings MUST correspond to the ID() values of other registered analyzers.
	// Implementations MUST NOT introduce circular dependencies (directly or indirectly).
	//
	// Analyzers may depend only on other analyzers of the same type.
	// For example, a ProposalAnalyzer may only depend on other ProposalAnalyzer instances,
	// a BatchOperationAnalyzer may only depend on other BatchOperationAnalyzer instances,
	// and a CallAnalyzer may only depend on other CallAnalyzer instances.
	// This restriction exists because analyzers of different types are already executed in a fixed dependency order:
	// parameter analyzers run before call analyzers, which run before batch operation analyzers, which in turn run before proposal analyzers.
	Dependencies() []string
}

type BatchOperationAnalyzer interface {
	BaseAnalyzer
	CanAnalyze(ctx context.Context, req AnalyzeRequest, operation decoder.DecodedBatchOperation) bool
	Analyze(ctx context.Context, req AnalyzeRequest, operation decoder.DecodedBatchOperation) (Annotations, error)
}

type CallAnalyzer interface {
	BaseAnalyzer
	CanAnalyze(ctx context.Context, req AnalyzeRequest, call decoder.DecodedCall) bool
	Analyze(ctx context.Context, req AnalyzeRequest, call decoder.DecodedCall) (Annotations, error)
}

type ExecutionContext interface {
	Domain() cldfdomain.Domain
	EnvironmentName() string
	BlockChains() chain.BlockChains
	DataStore() datastore.DataStore
}

type ParameterAnalyzer interface {
	BaseAnalyzer
	CanAnalyze(ctx context.Context, req AnalyzeRequest, param decoder.DecodedParameter) bool
	Analyze(ctx context.Context, req AnalyzeRequest, param decoder.DecodedParameter) (Annotations, error)
}

type ProposalAnalyzer interface {
	BaseAnalyzer
	CanAnalyze(ctx context.Context, req AnalyzeRequest, proposal decoder.DecodedTimelockProposal) bool
	Analyze(ctx context.Context, req AnalyzeRequest, proposal decoder.DecodedTimelockProposal) (Annotations, error)
}