codeapi

type CallEdge struct {
	CallerID ast.NodeID
	CalleeID ast.NodeID
	CallSite *Location // where the call occurs
}

type CallGraph struct {
	Root      *CallNode
	Nodes     map[ast.NodeID]*CallNode
	Edges     []*CallEdge
	Direction Direction
	MaxDepth  int
	Truncated bool // true if results were limited
}

type CallGraphOptions struct {
	Direction       Direction
	MaxDepth        int
	IncludeExternal bool         // include calls to external packages
	IncludeTests    bool         // include test files
	StopAt          []ast.NodeID // don't traverse past these nodes
}

type CallNode struct {
	ID        ast.NodeID
	Name      string
	ClassName string // empty if top-level function
	FilePath  string
	FileID    int32
	Depth     int // distance from root
	Range     base.Range
}

type ClassFilter struct {
	Name     string // exact match
	NameLike string // pattern match (e.g., "*Service")
	FilePath string // exact file path
	FileID   *int32

	Limit  int
	Offset int
}

type ClassInfo struct {
	ID       ast.NodeID
	Name     string
	FilePath string
	FileID   int32
	Range    base.Range
	Language string

	// Metadata contains additional attributes (e.g., annotations, modifiers)
	Metadata map[string]any `json:"metadata,omitempty"`

	// Populated on demand
	Methods []*MethodInfo
	Fields  []*FieldInfo

	// Inheritance
	ParentClasses []ast.NodeID
	ChildClasses  []ast.NodeID
}

type ClassWithCallGraph struct {
	Class       *ClassInfo
	MethodCalls map[ast.NodeID]*CallGraph // methodID -> call graph
}

type CodeAPI interface {
	// Reader returns the CodeReader for entity queries
	Reader() CodeReader

	// Analyzer returns the GraphAnalyzer for graph traversals
	Analyzer() GraphAnalyzer

	// ExecuteCypher executes a raw Cypher query and returns the results.
	// Use this for complex queries not covered by Reader or Analyzer.
	// The query should be read-only; use ExecuteCypherWrite for mutations.
	ExecuteCypher(ctx context.Context, query string, params map[string]any) ([]map[string]any, error)

	// ExecuteCypherWrite executes a write Cypher query (create, update, delete).
	// Returns the result records if any.
	ExecuteCypherWrite(ctx context.Context, query string, params map[string]any) ([]map[string]any, error)
}

type CodeReader interface {
	// Repo returns a reader scoped to a specific repository
	Repo(name string) RepoReader

	// ListRepos returns all available repository names
	ListRepos(ctx context.Context) ([]string, error)
}

type DependencyEdge struct {
	SourceID ast.NodeID
	TargetID ast.NodeID
	FlowType string // "assignment", "parameter", "return", etc.
}

type DependencyGraph struct {
	Root      *DependencyNode
	Nodes     map[ast.NodeID]*DependencyNode
	Edges     []*DependencyEdge
	Direction Direction
	Truncated bool
}

type DependencyNode struct {
	ID       ast.NodeID
	Name     string
	NodeType ast.NodeType
	FilePath string
	FileID   int32
	Depth    int
}

type DependencyOptions struct {
	MaxDepth        int
	IncludeIndirect bool           // transitive dependencies
	FilterTypes     []ast.NodeType // only return these node types
}

type Direction string

type FieldAccessResult struct {
	Field   *FieldInfo
	Readers []*MethodAccessInfo // methods that read this field
	Writers []*MethodAccessInfo // methods that write this field
}

type FieldFilter struct {
	Name       string
	NameLike   string
	ClassName  string
	ClassID    *ast.NodeID
	Visibility *Visibility

	Limit  int
	Offset int
}

type FieldInfo struct {
	ID         ast.NodeID
	Name       string
	Type       string
	ClassID    ast.NodeID
	Range      base.Range
	Visibility Visibility
	IsStatic   bool

	// Metadata contains additional attributes (e.g., annotations, modifiers)
	Metadata map[string]any `json:"metadata,omitempty"`
}

type FileFilter struct {
	Path     string
	PathLike string // pattern match
	Language string

	Limit  int
	Offset int
}

type FileInfo struct {
	ID       ast.NodeID
	Path     string
	Language string
	FileID   int32
	RepoName string

	// Metadata contains additional attributes
	Metadata map[string]any `json:"metadata,omitempty"`

	// Populated on demand
	Classes   []*ClassInfo
	Functions []*MethodInfo // top-level functions
}

type FileReader interface {
	// Path returns the file path
	Path() string

	// FileID returns the file ID (0 if not yet resolved)
	FileID() int32

	// Info returns the file info
	Info(ctx context.Context) (*FileInfo, error)

	// ListClasses returns all classes in this file
	ListClasses(ctx context.Context) ([]*ClassInfo, error)

	// FindClassByName finds a class by name in this file
	FindClassByName(ctx context.Context, name string) (*ClassInfo, error)

	// ListMethods returns all methods (class methods) in this file
	ListMethods(ctx context.Context) ([]*MethodInfo, error)

	// ListFunctions returns all top-level functions in this file
	ListFunctions(ctx context.Context) ([]*MethodInfo, error)

	// FindMethodByName finds a method/function by name in this file
	FindMethodByName(ctx context.Context, name string) (*MethodInfo, error)

	// FindMethodInClass finds a method by name within a specific class
	FindMethodInClass(ctx context.Context, methodName, className string) (*MethodInfo, error)

	// ListFields returns all fields in this file
	ListFields(ctx context.Context) ([]*FieldInfo, error)

	// FindFieldByName finds a field by name, optionally scoped to a class
	FindFieldByName(ctx context.Context, fieldName, className string) (*FieldInfo, error)
}

type FindAndAnalyzeRequest struct {
	RepoName string
	FilePath string // optional, narrows search
	Name     string
	NodeType ast.NodeType // Function, Class, Field, Variable

	// Analysis options
	IncludeCallGraph bool
	CallGraphDepth   int
	IncludeDataFlow  bool
	DataFlowDepth    int
}

type FindAndAnalyzeResult struct {
	// The found entity (one of these will be set)
	Class    *ClassInfo
	Method   *MethodInfo
	Field    *FieldInfo
	Variable *VariableInfo

	// Analysis results
	CallGraph *CallGraph
	DataFlow  *DependencyGraph
	Impact    *ImpactResult
}

type GraphAnalyzer interface {

	// GetCallGraph returns the call graph starting from a function.
	// Use opts.Direction to control whether to get callees, callers, or both.
	GetCallGraph(ctx context.Context, functionID ast.NodeID, opts CallGraphOptions) (*CallGraph, error)

	// GetCallGraphByName finds a function by name and returns its call graph.
	// If className is empty, searches for top-level functions.
	// If filePath is empty, searches across all files in the repo.
	GetCallGraphByName(ctx context.Context, repoName, filePath, className, functionName string, opts CallGraphOptions) (*CallGraph, error)

	// GetCallers returns functions that call the specified function (convenience method).
	// Equivalent to GetCallGraph with Direction=Incoming.
	GetCallers(ctx context.Context, functionID ast.NodeID, maxDepth int) (*CallGraph, error)

	// GetCallees returns functions called by the specified function (convenience method).
	// Equivalent to GetCallGraph with Direction=Outgoing.
	GetCallees(ctx context.Context, functionID ast.NodeID, maxDepth int) (*CallGraph, error)

	// GetDataDependents returns nodes that depend on the value of the specified node.
	// Follows DATA_FLOW edges outward to find what uses this value.
	GetDataDependents(ctx context.Context, nodeID ast.NodeID, opts DependencyOptions) (*DependencyGraph, error)

	// GetDataSources returns nodes that contribute to the value of the specified node.
	// Follows DATA_FLOW edges backward to find where values come from.
	GetDataSources(ctx context.Context, nodeID ast.NodeID, opts DependencyOptions) (*DependencyGraph, error)

	// GetVariableDependents returns functions/methods that depend on a variable's value.
	// This is a higher-level query that finds the variable and traces its usage.
	GetVariableDependents(ctx context.Context, repoName, filePath, variableName string, opts DependencyOptions) (*DependencyGraph, error)

	// GetFieldAccessors returns methods that read or write a specific field.
	GetFieldAccessors(ctx context.Context, fieldID ast.NodeID) (*FieldAccessResult, error)

	// GetFieldAccessorsByName finds a field by name and returns its accessors.
	GetFieldAccessorsByName(ctx context.Context, repoName, className, fieldName string) (*FieldAccessResult, error)

	// GetInheritanceTree returns the inheritance hierarchy for a class.
	// Includes both ancestors (parents) and descendants (children).
	GetInheritanceTree(ctx context.Context, classID ast.NodeID) (*InheritanceTree, error)

	// GetParentClasses returns direct and indirect parent classes.
	GetParentClasses(ctx context.Context, classID ast.NodeID, maxDepth int) ([]*ClassInfo, error)

	// GetChildClasses returns direct and indirect child classes.
	GetChildClasses(ctx context.Context, classID ast.NodeID, maxDepth int) ([]*ClassInfo, error)

	// GetImpact returns all code elements that could be affected by changes to the specified node.
	// This combines call graph and data flow analysis.
	GetImpact(ctx context.Context, nodeID ast.NodeID, opts ImpactOptions) (*ImpactResult, error)

	// GetImpactByName is a convenience method for impact analysis by name.
	GetImpactByName(ctx context.Context, repoName, filePath, name string, nodeType ast.NodeType, opts ImpactOptions) (*ImpactResult, error)
}

type ImpactNode struct {
	ID       ast.NodeID
	Name     string
	NodeType ast.NodeType
	FilePath string
	FileID   int32
	Depth    int
	Impact   ImpactType // how this node is affected
}

type ImpactOptions struct {
	MaxDepth         int  // max traversal depth (-1 for unlimited)
	IncludeCallGraph bool // include callers in impact
	IncludeDataFlow  bool // include data dependents in impact
	IncludeTests     bool // include test files
	Scope            ImpactScope
}

type ImpactResult struct {
	// Source is the node being analyzed
	Source *ImpactNode

	// AffectedNodes are nodes that could be affected by changes
	AffectedNodes []*ImpactNode

	// AffectedByCallGraph are nodes affected via call relationships
	AffectedByCallGraph []*ImpactNode

	// AffectedByDataFlow are nodes affected via data dependencies
	AffectedByDataFlow []*ImpactNode

	// Summary statistics
	TotalAffected   int
	MaxDepthReached int
	Truncated       bool
}

type ImpactScope string

type ImpactType string

type InheritanceNode struct {
	ID       ast.NodeID
	Name     string
	FilePath string
	Parents  []*InheritanceNode
	Children []*InheritanceNode
	Depth    int
}

type InheritanceTree struct {
	Root     *InheritanceNode
	Nodes    map[ast.NodeID]*InheritanceNode
	MaxDepth int
}

type LoadOptions struct {
	IncludeMethods     bool
	IncludeFields      bool
	IncludeInheritance bool
	IncludeParameters  bool
}

type Location struct {
	FilePath string
	FileID   int32
	Range    base.Range
}

type MethodAccessInfo struct {
	Method      *MethodInfo
	AccessCount int        // number of times the field is accessed
	Locations   []Location // where in the method the access occurs
}

type MethodFilter struct {
	Name      string
	NameLike  string
	ClassName string
	ClassID   *ast.NodeID
	FilePath  string
	FileID    *int32

	IsMethod   *bool // nil = any, true = methods only, false = functions only
	IsAccessor *bool

	Limit  int
	Offset int
}

type MethodInfo struct {
	ID       ast.NodeID
	Name     string
	FilePath string
	FileID   int32
	Range    base.Range

	// Context
	ClassName string
	ClassID   ast.NodeID
	IsMethod  bool // true if belongs to a class, false if top-level function

	// Signature
	Parameters []*ParameterInfo
	ReturnType string

	// Flags
	IsAccessor    bool
	IsConstructor bool
	IsStatic      bool
	Visibility    Visibility

	// Metadata contains additional attributes (e.g., annotations, modifiers)
	Metadata map[string]any `json:"metadata,omitempty"`
}

type MethodWithContext struct {
	Method  *MethodInfo
	Class   *ClassInfo // nil if top-level function
	File    *FileInfo
	Callers *CallGraph
	Callees *CallGraph
}

type ParameterInfo struct {
	ID       ast.NodeID
	Name     string
	Type     string
	Position int
}

type RepoReader interface {
	// Name returns the repository name
	Name() string

	// ListFiles returns files in the repository with pagination
	ListFiles(ctx context.Context, limit, offset int) ([]*FileInfo, error)

	// FindFiles returns files matching the filter
	FindFiles(ctx context.Context, filter FileFilter) ([]*FileInfo, error)

	// GetFile returns a file by its ID
	GetFile(ctx context.Context, id ast.NodeID) (*FileInfo, error)

	// GetFileByPath returns a file by its path
	GetFileByPath(ctx context.Context, path string) (*FileInfo, error)

	// File returns a reader scoped to a specific file
	File(path string) FileReader

	// FileByID returns a reader scoped to a specific file by ID
	FileByID(id int32) FileReader

	// ListClasses returns classes in the repository with pagination
	ListClasses(ctx context.Context, limit, offset int) ([]*ClassInfo, error)

	// FindClasses returns classes matching the filter
	FindClasses(ctx context.Context, filter ClassFilter) ([]*ClassInfo, error)

	// GetClass returns a class by its ID
	GetClass(ctx context.Context, id ast.NodeID) (*ClassInfo, error)

	// GetClassFull returns a class with methods and fields populated
	GetClassFull(ctx context.Context, id ast.NodeID, opts LoadOptions) (*ClassInfo, error)

	// FindClassByName finds a class by name (returns first match)
	FindClassByName(ctx context.Context, name string) (*ClassInfo, error)

	// ListMethods returns methods in the repository with pagination
	ListMethods(ctx context.Context, limit, offset int) ([]*MethodInfo, error)

	// ListFunctions returns top-level functions (not class methods) with pagination
	ListFunctions(ctx context.Context, limit, offset int) ([]*MethodInfo, error)

	// FindMethods returns methods matching the filter
	FindMethods(ctx context.Context, filter MethodFilter) ([]*MethodInfo, error)

	// GetMethod returns a method by its ID
	GetMethod(ctx context.Context, id ast.NodeID) (*MethodInfo, error)

	// FindMethodByName finds a method by name and optional class
	FindMethodByName(ctx context.Context, methodName string, className string) (*MethodInfo, error)

	// FindFields returns fields matching the filter
	FindFields(ctx context.Context, filter FieldFilter) ([]*FieldInfo, error)

	// GetField returns a field by its ID
	GetField(ctx context.Context, id ast.NodeID) (*FieldInfo, error)

	// GetClassMethods returns all methods belonging to a class
	GetClassMethods(ctx context.Context, classID ast.NodeID) ([]*MethodInfo, error)

	// GetClassFields returns all fields belonging to a class
	GetClassFields(ctx context.Context, classID ast.NodeID) ([]*FieldInfo, error)

	// GetMethodClass returns the class containing a method (nil if top-level function)
	GetMethodClass(ctx context.Context, methodID ast.NodeID) (*ClassInfo, error)
}

type VariableInfo struct {
	ID       ast.NodeID
	Name     string
	Type     string
	FilePath string
	FileID   int32
	Range    Location
	Scope    string // "local", "parameter", "global"
}

type Visibility string