lens

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

type AnalysisEngine struct {
	Config                 *Config
	ModuleChangeProvider   ModuleChangeProvider
	CallerAnalysisProvider CallerAnalysisProvider
	TestProvider           TestProvider
	UpdateAnalysisProvider UpdateAnalysisProvider
	MutationTester         MutationTester
	TestResultAnalyzer     TestResultAnalyzer
	StorageProvider        StorageProvider
	ReportWriter           ReportWriter
}

type CallFrame struct {
	// FieldValues records the captured state.
	FieldValues FieldValues `msgpack:"f"`
	// Stack holds the call stack.
	Stack []StackFrame `msgpack:"s"`
	// TimeMillis is the execution time in milliseconds since process start.
	TimeMillis uint32 `msgpack:"t"`
}

type CallerAnalysisProvider interface {
	// PerformCallerStaticAnalysis analyzes the project's source code to find all
	// functions that directly or indirectly call the changed module functions.
	// It builds a call graph to trace how module changes might affect project code.
	//
	// Parameters:
	//   - config: configuration containing paths and settings for analysis
	//   - moduleChanges: list of functions in dependencies that have changed
	//
	// Returns:
	//   - []*CallerFunction: list of project functions that call changed module functions
	//   - ReachableModuleChange: mapping of which module changes are reachable from project code
	//   - error: any error encountered during static analysis
	PerformCallerStaticAnalysis(config Config, moduleChanges []*ModuleFunction) ([]*CallerFunction, ReachableModuleChange, error)

	// Cleanup is invoked after engine analysis is complete, allowing freeing of resources used during static analysis.
	Cleanup()
}

type CallerFunction struct {
	Function

	// ChangeFunctions lists changed functions invoked by this caller.
	ChangeFunctions []*ModuleFunction
}

type Config struct {
	ProjectDir, ModuleVersionFlag, ModulesVersionFlag     string
	UpdatedGoModFile, UpdatedGoWorkFile                   string
	AstMonitorPort, MaxFieldRecurse, MaxFieldLen, CacheMB int
	ReportJsonFile, ReportChartsFile                      string
	MutationScope, MutationMode, MutationTests            string
	TmpCopy                                               bool
	TimeMultiplier                                        int
	// Computed fields
	Gopath, Gomodcache, AbsProjDir string
	// Parsed target modules from flags
	TargetModules []TargetModule
	// Custom flags support - all stored as strings for ease of use
	CustomFlags map[string]string
	// contains filtered or unexported fields
}

type DefaultCallerAnalysisProvider struct {
	// PostCallerAnalysis is an optional hook called after project caller static analysis completes.
	//
	// The hook is called once after all project callers have been identified.
	//
	// Parameters:
	//   - projectPackages: Project packages with type information from static analysis
	//   - modulePackages: Module (dependency) packages with type information from static analysis
	//   - identEdges: Call graph edges mapping function idents to callees
	//   - moduleChanges: All functions that changed in module updates
	//   - callers: Project functions that call into changed module functions
	//   - reachable: Map of which module changes are reachable from project code
	//
	// The package parameters provide access to type information for accurate analysis.
	// Project and module packages are separated to enable targeted analysis.
	// The identEdges parameter provides a simplified view of the project call graph,
	// enabling extensions to perform additional reachability analysis without needing
	// to reload the expensive SSA call graph.
	//
	// Returns:
	//   - error: Any fatal error encountered during analysis.
	PostCallerAnalysis func(projectPackages []*packages.Package, modulePackages []*packages.Package,
		identEdges map[string][]string, callers []*CallerFunction, reachable ReachableModuleChange) error
}

type DefaultModuleChangeProvider struct{}

type DefaultMutationTester struct{}

type DefaultReportWriter struct{}

type DefaultStorageProvider struct {
	Path    string
	CacheMB int
	// contains filtered or unexported fields
}

type DefaultTestProvider struct{}

type DefaultTestResultAnalyzer struct{}

type DefaultUpdateAnalysisProvider struct {
	// PreUpdateExtensionConfig is an optional function called before the first test run (old module version).
	// Returns a map of point IDs to frame keys for storage.
	PreUpdateExtensionConfig func(astEditor *ASTModifier) (map[uint32]*string, error)

	// PostUpdateExtensionConfig is an optional function called before the second test run (new module version).
	// Returns a map of point IDs to frame keys for storage.
	PostUpdateExtensionConfig func(astEditor *ASTModifier) (map[uint32]*string, error)
}

type FieldValue struct {
	// Value holds the string representation.
	Value string `msgpack:"v"`
	// Children contains nested field values.
	Children FieldValues `msgpack:"c,omitempty"`
}

type FieldValues map[string]*FieldValue

type Function struct {
	// FilePath is the full path to the source file.
	FilePath string
	// PackageName is the package containing the function.
	PackageName string
	// FunctionIdent is the fully qualified identifier.
	FunctionIdent string
	// FunctionName is the short function name.
	FunctionName string
	// EntryLineNumber is the entry line.
	EntryLineNumber uint32
	// ReturnPoints lists source return locations.
	ReturnPoints []FunctionReturn
	// ReturnPanic reports if the function always panics.
	ReturnPanic bool
}

type FunctionReturn struct {
	// Line is the return line number.
	Line uint32
	// CallCount is the number of call expressions returned.
	CallCount uint32
}

type LensMonitorField struct {
	Name     string // field name or path
	Type     string // Go type specific
	Value    interface{}
	Children []LensMonitorField // nested fields for structs, maps, etc
}

type LensMonitorMessageError struct {
	PointID uint32 // instrumented point id (provided to client from AST)
	Message string
	Stack   []lensMonitorStackFrame // call stack frames
}

type LensMonitorMessagePoint struct {
	PointID uint32                  // instrumented point id (provided to client from AST)
	TimeNS  int64                   // nanoseconds since the process start
	Stack   []lensMonitorStackFrame // call stack frames
}

type LensMonitorMessagePointPanic struct {
	PointID uint32 // instrumented point id (provided to client from AST)
	TimeNS  int64  // nanoseconds since the process start
	Message string // value from the panic recovery
}

type LensMonitorMessagePointState struct {
	PointID uint32                  // instrumented point id (provided to client from AST)
	TimeNS  int64                   // nanoseconds since the process start
	Stack   []lensMonitorStackFrame // call stack frames
	Fields  []LensMonitorField      // variables reachable within the function scope (parameters, local values, etc)
}

type LimitingWaitGroup interface {
	// Take blocks until the wait group has capacity.
	Take()
	// Release should be invoked (typically in defer) to indicate the activity following Take() has completed.
	Release()
	// Join will block until all activities have completed. This implementation expects that once Join() is invoked, Take() will NOT be invoked again.
	Join()
}

type MinimumTestFunction struct {
	// FunctionIdent is the fully qualified identifier.
	FunctionIdent string
	// FunctionName is the short name.
	FunctionName string
}

type ModuleChange struct {
	// Name is the module name.
	Name string
	// PriorVersion is the version before update.
	PriorVersion string
	// NewVersion is the version after update.
	NewVersion string
	// Indirect indicates the module is an indirect dependency.
	Indirect bool
	// GoVersion is the minimum Go version from the module's go.mod (oldest of old/new versions).
	GoVersion string
}

type ModuleChangeProvider interface {
	// AnalyzeModuleChanges examines the differences between module versions to identify changed functions.
	//
	// Parameters:
	//   - config: configuration containing paths and settings for analysis
	//   - analyzeExpandTransitive: if true, recursively analyzes transitive dependency changes
	//   - changedModules: list of modules that have version changes to analyze
	//   - neighbourRadius: radius for marking changed lines in function definitions (used for mutation testing scope)
	//
	// Returns:
	//   - map[string][]*ModuleFunction: changed functions organized by module name (OLD version)
	//   - map[string][]*packages.Package: NEW version packages with type information (keyed by module name)
	//   - error: any error encountered during analysis
	AnalyzeModuleChanges(config Config, analyzeExpandTransitive bool,
		changedModules []*ModuleChange, neighbourRadius int) (map[string][]*ModuleFunction, map[string][]*packages.Package, error)

	// Cleanup is invoked after engine analysis is complete, allowing freeing of resources used during analysis.
	Cleanup()
}

type ModuleFunction struct {
	Function

	// Definition contains the function's source code from the analyzed version.
	Definition string
	// LineChangeBitmap marks which lines changed between versions.
	// The bitmap indices correspond to lines in this function's Definition.
	// For unchanged functions, this is empty/nil.
	// New function defs will always have a LineChangeBitmap of radius 0 to show exact line changes.
	LineChangeBitmap []bool
	// Module identifies which module this function belongs to, including version information.
	Module *ModuleChange
}

type ModuleMetrics struct {
	RootModuleName            string   `json:"root_module_name"`
	RootModuleStartVersion    string   `json:"root_module_start_version"`
	RootModuleUpdateVersion   string   `json:"root_module_update_version"`
	ChangedModules            []string `json:"changed_modules"`
	ChangedModuleCount        int      `json:"changed_module_count"`
	ChangeFuncCount           int      `json:"changed_function_count"`
	ReachableChangedFunctions []string `json:"reachable_changed_functions"`
	ReachableChangedFuncCount int      `json:"reachable_changed_function_count"`
	UntrackedModuleFuncCount  int      `json:"untracked_module_function_count"`
}

type MutationResult struct {
	// MutationCount is the total mutations executed.
	MutationCount int
	// SquashedCount is the number of deduplicated mutations.
	SquashedCount int
}

type MutationTester interface {
	// RunMutationTesting applies mutations to the changed module functions and runs
	// the relevant tests to validate test coverage. It uses go-mutesting to introduce
	// code mutations and checks if the test suite can detect the introduced changes.
	//
	// Parameters:
	//   - config: configuration containing paths and settings for analysis
	//   - fastMutations: if true, use fast mutation mode (fewer mutations for speed)
	//   - lineScopedMutations: if true, limit mutations to specific changed lines
	//   - runTargetedTests: if true, run only tests that target the changed functions
	//   - moduleChanges: list of module functions that have changed
	//   - testFunctions: list of test functions to run during mutation testing
	//
	// Returns:
	//   - MutationResult: results of mutation testing including mutation scores and details
	//   - error: any error encountered during mutation testing
	RunMutationTesting(config Config, fastMutations, lineScopedMutations,
		runTargetedTests bool, moduleChanges []*ModuleFunction, testFunctions []*TestFunction) (MutationResult, error)

	// Cleanup is invoked after engine analysis is complete, allowing freeing resources used during mutation testing.
	Cleanup()
}

type PerformanceChange struct {
	TestFunctionIdent string `json:"test_function_ident"` // identifier of the test function
	TestFunctionName  string `json:"test_function_name"`  // name of the test function
	CallerIdent       string `json:"caller_ident"`        // identifier of the caller function
	TimeDiffMs        int64  `json:"time_diff_ms"`        // time interval difference in milliseconds (positive = slower, negative = faster)
	PreTimeMs         uint32 `json:"pre_time_ms"`         // call interval before change in milliseconds
	PostTimeMs        uint32 `json:"post_time_ms"`        // call interval after change in milliseconds
}

type PerformanceTimeChange struct {
	TimeDiff   time.Duration // time interval difference (positive = slower, negative = faster)
	PreTimeMs  uint32        // call interval before change in milliseconds
	PostTimeMs uint32        // call interval after change in milliseconds
}

type ReachableModuleChange map[string]*ModuleFunction

type ReportMap map[string]interface{}

type ReportMetrics struct {
	GeneratedAt           time.Time         `json:"generated_at"`
	RunDuration           int64             `json:"run_ms"`
	AnalysisDuration      int64             `json:"analysis_ms"`
	TestDiscoveryDuration int64             `json:"test_discovery_ms"`
	FieldCheckDuration    int64             `json:"field_check_ms"`
	MutationDuration      int64             `json:"mutation_ms"`
	Module                ModuleMetrics     `json:"module"`
	Validation            ValidationMetrics `json:"validation"`
}

type ReportWriter interface {
	// WriteReportFiles generates and writes analysis reports to the specified file paths.
	// It creates both JSON and chart-based reports containing all analysis results,
	// including timing information, test results, mutation testing results, and
	// behavioral change summaries.
	//
	// Parameters:
	//   - reportJsonFile: path where the JSON report should be written
	//   - reportChartsFile: path where the chart report should be written
	//   - startTime: when the analysis started (for computing total duration)
	//   - analysisTime: duration of module change analysis
	//   - testDiscoveryTime: duration of test discovery or generation
	//   - testExecutionTime: duration of test execution with monitoring
	//   - mutationTime: duration of mutation testing
	//   - changedModules: list of modules with version changes
	//   - checkedModules: list of all modules that were analyzed
	//   - moduleChangeCount: total number of changed functions across all modules
	//   - moduleChangesReachedInTesting: number of module changes exercised by tests
	//   - untrackedModuleFuncs: number of module functions skipped due to Go version incompatibility
	//   - projectFieldChecks: number of field value checks performed on project code
	//   - callingFunctions: project functions that call changed module functions
	//   - testFunctions: test functions that exercise the affected code
	//   - sameCount: number of test cases with identical behavior before/after update
	//   - diffCount: number of test cases with different behavior before/after update
	//   - testReports: detailed reports of behavioral differences found
	//   - globalMutations: results from mutation testing
	//
	// Returns:
	//   - error: any error encountered during report generation or file writing
	WriteReportFiles(reportJsonFile, reportChartsFile string, startTime time.Time,
		analysisTime, testDiscoveryTime, testExecutionTime, mutationTime time.Duration,
		changedModules []*ModuleChange, checkedModules []string, moduleChangeCount, moduleChangesReachedInTesting, untrackedModuleFuncs int,
		projectFieldChecks int, callingFunctions []*CallerFunction, testFunctions []*TestFunction,
		sameCount, diffCount int, testReports []TestReport,
		globalMutations MutationResult) error
}

type SingletonStorageProvider struct {
	Store Storage
}

type StackFrame struct {
	// File is the source file path.
	File string `msgpack:"fi"`
	// Line is the line number.
	Line uint32 `msgpack:"li"`
	// Function is the function identifier.
	Function string `msgpack:"fu"`
}

type Storage interface {
	SaveState(key string, blob []byte) error
	LoadState(key string) ([]byte, bool, error)
	DeleteState(key string) error
	// ListKeysPrefix returns all keys in the store that begin with the given prefix.
	ListKeysPrefix(prefix string) ([]string, error)
	// ListKeys returns all keys in the store.
	ListKeys() ([]string, error)
	Clear() error
	Close()
}

type StorageProvider interface {
	// NewStorage creates a new storage instance for persisting test results and
	// other analysis data. The storage is used to save captured runtime information
	// during test execution and retrieve it during result comparison.
	//
	// Returns:
	//   - Storage: a new storage interface instance
	//   - error: any error encountered during storage creation
	NewStorage() (Storage, error)
}

type TargetModule struct {
	Name    string
	Version string
}

type TestDetail struct {
	TestFunctionIdent    string                       `json:"test_function_ident"` // ident of the test
	TestFunctionName     string                       `json:"test_function_name"`
	BaselineFailure      bool                         `json:"baseline_failure"`
	PassRegression       bool                         `json:"pass_regression"`         // Did the test fail only after the change
	DiffFieldCount       int                          `json:"diff_field_count"`        // how many fields changed
	ModuleChangeHitCount int                          `json:"module_change_hit_count"` // how many module functions that test reached
	FieldChanges         map[string]map[string]string `json:"field_changes"`           // [callerIdent][fieldName]valueDiff
}

type TestFunction struct {
	Function

	// Targets lists callers tested by this function.
	Targets []*CallerFunction
}

type TestProvider interface {
	// ProvideTests discovers existing test functions that exercise the calling functions.
	// Advanced implementations may optionally generate additional tests to improve coverage.
	//
	// Parameters:
	//   - config: configuration containing paths and settings for analysis
	//   - callingFunctions: list of project functions that call changed module functions
	//
	// Returns:
	//   - []*TestFunction: list of test functions that exercise the affected code
	//   - error: any error encountered during test discovery or generation
	ProvideTests(config Config, callingFunctions []*CallerFunction) ([]*TestFunction, error)

	// Cleanup is invoked after engine analysis is complete, allowing freeing resources used during test provision.
	Cleanup()
}

type TestReport struct {
	OriginalResult      TestResult // OriginalResult must be used to get mutation hit counts
	PostUpdateResult    TestResult
	CallerFieldChanges  map[string]map[string]string     // [callerIdent][fieldName]valueDiff
	CallerTimeChanges   map[string]PerformanceTimeChange // [callerIdent]detailed timing info
	TestRegressionCount int
	SameFieldCount      int
	DiffFieldCount      int
}

type TestResult struct {
	// TestFunction identifies the test.
	TestFunction MinimumTestFunction
	// CallerResults maps callers to captured field values.
	CallerResults map[string][]CallFrame
	// ProjectPanics records panic messages from project functions.
	ProjectPanics map[string][]string
	// ModulePanics records panic messages from module functions.
	ModulePanics map[string][]string
	// ModuleChangesHit counts the changed functions hit.
	ModuleChangesHit int
	// TestFailure reports if the test failed.
	TestFailure bool
	// ExtensionFrames are filled in if extension AST modifications are configured through ExtensionPointConfig.
	// ExtensionFrames shares the same deduplication pool as CallerResults for efficient storage.
	// Keys should be namespaced (e.g., "security:network:dial").
	ExtensionFrames map[string][]CallFrame
}

type TestResultAnalyzer interface {
	// CompareTestResults analyzes the differences between pre-update and post-update
	// test execution results. It compares captured field values, function call sequences,
	// timing information, and other runtime behavior to detect changes.
	//
	// Parameters:
	//   - preResults: storage containing test results from before the module update
	//   - postResults: storage containing test results from after the module update
	//   - timeMultiplier: multiplier for timing tolerances (higher values are more lenient)
	//
	// Returns:
	//   - int: number of test cases with identical behavior (same results)
	//   - int: number of test cases with different behavior (different results)
	//   - []TestReport: detailed reports of differences found between test runs
	//   - error
	CompareTestResults(preResults, postResults Storage, timeMultiplier int) (int, int, []TestReport, error)
}

type UpdateAnalysisProvider interface {
	// RunModuleUpdateAnalysis runs tests with AST instrumentation to capture runtime
	// behavior before and after module updates. It injects monitoring code to record
	// function calls, field states, panics, and timing information.
	//
	// Parameters:
	//   - config: configuration containing paths and settings for analysis
	//   - storage: storage interface for persisting test results
	//   - changedModules: list of modules that have version changes
	//   - reachableModuleChanges: mapping of module changes reachable from project code
	//   - callingFunctions: project functions that call changed module functions
	//   - testFunctions: test functions that exercise the affected code
	//
	// Returns:
	//   - int: number of project field checks performed
	//   - int: number of module changes reached during testing
	//   - int: number of module functions skipped due to Go version incompatibility
	//   - Storage: pre-update test results storage
	//   - Storage: post-update test results storage
	//   - error: any error encountered during analysis
	RunModuleUpdateAnalysis(config Config, storage Storage, changedModules []*ModuleChange, reachableModuleChanges ReachableModuleChange,
		callingFunctions []*CallerFunction, testFunctions []*TestFunction) (int, int, int, Storage, Storage, error)

	// Cleanup is invoked after engine analysis is complete, allowing freeing of resources used during update analysis.
	Cleanup()
}

type ValidationMetrics struct {
	RelevantProjectFunctions   []string            `json:"relevant_project_functions"`
	RelevantProjectFuncCount   int                 `json:"relevant_project_function_count"`
	RelevantTestFunctions      []string            `json:"relevant_test_functions"`
	RelevantTestFuncCount      int                 `json:"relevant_test_function_count"`
	ProjectFieldCheckPoints    int                 `json:"project_field_check_point_count"`
	ModuleChangeHitInTestCount int                 `json:"module_change_hit_in_test_count"`
	TestFieldMatchCount        int                 `json:"test_field_match_count"`
	TestFieldDiffCount         int                 `json:"test_field_diff_count"`
	GeneratedTestFuncCount     int                 `json:"generated_test_function_count"`
	MutationCount              int                 `json:"mutation_count"`
	MutationsSquashed          int                 `json:"mutations_squashed"`
	PerformanceChanges         []PerformanceChange `json:"performance_changes"` // detected performance changes
	TestDetails                []TestDetail        `json:"test_details"`
}