types

type AccessLevel uint8

type AccessPattern struct {
	// All detected accesses in order
	Accesses []FieldAccess

	// Overall pattern classification
	Pattern AccessPatternType

	// Per-target analysis
	TargetPatterns map[string]*TargetAccessPattern

	// Detected violations/concerns
	Violations []PatternViolation

	// Summary statistics
	TotalReads      int
	TotalWrites     int
	UniqueTargets   int
	ParameterWrites int
	ReceiverWrites  int
	GlobalWrites    int
	ClosureWrites   int
}

type AccessPatternType uint8

type AccessTarget uint8

type AccessType uint8

type AllocatorStats struct {
	TotalBlocks      int
	ActiveRefs       int64
	BlockSizeBytes   int
	TotalMemoryBytes int
	RefsPerBlock     int
}

type AnnotationType uint8

type AwaitData struct {
	Line        int      `json:"line"`
	AssignedVar string   `json:"assigned_var,omitempty"` // Variable receiving the result
	CallTarget  string   `json:"call_target,omitempty"`  // Function/method being awaited
	UsedVars    []string `json:"used_vars,omitempty"`    // Variables referenced in arguments
}

type BlockBoundary struct {
	Start int
	End   int
	Type  BlockType
	Name  string
	Depth int
}

type BlockType uint8

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

type CallArgument struct {
	Name      string `json:"name"`       // Argument name (if available)
	Type      string `json:"type"`       // Argument type (if available)
	Value     string `json:"value"`      // Argument value (if literal)
	IsLiteral bool   `json:"is_literal"` // Whether argument is a literal value
}

type CallData struct {
	Target    string `json:"target"` // Function/method name being called
	Line      int    `json:"line"`
	InLoop    bool   `json:"in_loop"`    // Whether this call is inside a loop
	LoopDepth int    `json:"loop_depth"` // Depth of containing loop (0 if not in loop)
	LoopLine  int    `json:"loop_line"`  // Line of containing loop
}

type CallType uint8

type ComponentInfo struct {
	Type        ComponentType `json:"type"`
	Name        string        `json:"name"`
	FilePath    string        `json:"file_path"`
	FileID      FileID        `json:"file_id"`
	Language    string        `json:"language"`
	Description string        `json:"description"`

	// Symbol information
	Symbols      []Symbol `json:"symbols"`
	Dependencies []string `json:"dependencies"` // Import paths, dependencies

	// Metadata for classification
	Patterns   []string               `json:"patterns"`   // Naming patterns that matched
	Confidence float64                `json:"confidence"` // Classification confidence (0-1)
	Evidence   []string               `json:"evidence"`   // Evidence for classification
	Metadata   map[string]interface{} `json:"metadata"`   // Additional component-specific data
}

type ComponentSearchOptions struct {
	Types         []ComponentType `json:"types"`          // Component types to find
	Language      string          `json:"language"`       // Specific language filter
	MinConfidence float64         `json:"min_confidence"` // Minimum classification confidence (default: 0.5)
	IncludeTests  bool            `json:"include_tests"`  // Include test components
	MaxResults    int             `json:"max_results"`    // Maximum results to return (default: 100)
}

type ComponentType int

type CompositeSymbolID struct {
	FileID        FileID // 32-bit file identifier
	LocalSymbolID uint32 // 32-bit symbol identifier within the file
}

type ContextAttribute struct {
	Type  ContextAttributeType `json:"type"`
	Value string               `json:"value"` // e.g., "use server", "@deprecated('Use foo instead')"
	Line  int                  `json:"line"`  // Line where attribute appears
}

type ContextAttributeType uint8

type ContextManifest struct {
	// Task description - free-form text for agents
	Task string `json:"t,omitempty"`

	// Metadata
	Created     time.Time `json:"c,omitempty"` // Creation timestamp
	Version     string    `json:"v,omitempty"` // Manifest format version
	ProjectRoot string    `json:"p,omitempty"` // Project root path for relative file paths

	// Symbol references - the core data
	Refs []ContextRef `json:"r"`

	// Statistics for display
	Stats ManifestStats `json:"s,omitempty"`
}

type ContextRef struct {
	// Location (at least one required: F+S, F+L, or just F)
	F string     `json:"f"`           // File path (required)
	S string     `json:"s,omitempty"` // Symbol name (optional - can use line range instead)
	L *LineRange `json:"l,omitempty"` // Line range (optional - can use symbol instead)

	// Expansion directives - what related code to fetch on hydration
	// Examples: "callers", "callees:2", "implementations", "tests"
	X []string `json:"x,omitempty"`

	// Metadata for agent-to-agent communication (LCI passes through, doesn't interpret)
	Role string `json:"role,omitempty"` // Semantic hint: "modify", "contract", "pattern", "boundary"
	Note string `json:"n,omitempty"`    // Free-form architect annotation

	// Internal tracking (not serialized to file, used during hydration)
	ObjectID string `json:"-"` // LCI internal object ID (populated during save)
}

type CrossLanguageLink struct {
	Target      CompositeSymbolID `json:"target"`      // Symbol in other language
	LinkType    CrossLinkType     `json:"link_type"`   // Type of cross-language link
	Language    string            `json:"language"`    // Target language
	Bridge      string            `json:"bridge"`      // How languages are bridged (FFI, API, etc.)
	Confidence  float64           `json:"confidence"`  // Confidence in the link (0-1)
	Description string            `json:"description"` // Human-readable description
}

type CrossLinkType uint8

type Definition struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	FilePath string `json:"file_path"`
	Line     int    `json:"line"`
	Column   int    `json:"column"`
}

type DependencyStrength uint8

type DependencyType uint8

type EnhancedCharacterMask struct {
	ASCIIMask     [4]uint64   // Fast bitmask for ASCII (0-255)
	UnicodeFilter BloomFilter // Bloom filter for Unicode characters (>255)
	HasUnicode    bool        // Optimization flag
}

type EnhancedSymbol struct {
	Symbol                   // Base symbol information
	ID           SymbolID    `json:"id"`
	IncomingRefs []Reference `json:"incoming_refs"`     // Symbols that reference this one
	OutgoingRefs []Reference `json:"outgoing_refs"`     // Symbols this one references
	ScopeChain   []ScopeInfo `json:"scope_chain"`       // Complete scope hierarchy
	RefStats     RefStats    `json:"ref_stats"`         // Aggregated reference statistics
	Metrics      interface{} `json:"metrics,omitempty"` // Code quality metrics (SymbolMetrics from analysis package)

	// Enhanced metadata for context analysis - MEMORY-CONSCIOUS VERSION
	// Use string fields but with clear documentation about memory implications
	TypeInfo    string   `json:"type_info,omitempty"`   // Type annotation (e.g., "string", "int", "*User")
	IsMutable   bool     `json:"is_mutable"`            // Whether the symbol is mutable (for variables)
	IsExported  bool     `json:"is_exported"`           // Whether the symbol is public/exported
	Annotations []string `json:"annotations,omitempty"` // Annotations like @lci:labels[tag], etc.
	DocComment  string   `json:"doc_comment,omitempty"` // Documentation comment
	Signature   string   `json:"signature,omitempty"`   // Function/method signature
	Complexity  int      `json:"complexity,omitempty"`  // Cyclomatic complexity for functions

	// Variable-specific metadata - COMPACT representation using bitfields
	VariableType  VariableType `json:"variable_type,omitempty"`  // Classification: global, local, parameter, field
	VariableFlags uint8        `json:"variable_flags,omitempty"` // Bitfield: bit0=const, bit1=static, bit2=pointer, bit3=array, bit4=channel, bit5=interface

	// Function-specific metadata - COMPACT representation
	ParameterCount uint8  `json:"parameter_count,omitempty"` // Number of parameters (0-255)
	FunctionFlags  uint8  `json:"function_flags,omitempty"`  // Bitfield: bit0=async, bit1=generator, bit2=method, bit3=variadic
	ReceiverType   string `json:"receiver_type,omitempty"`   // Method receiver type
}

type EnhancedSymbolInfo struct {
	ID         CompositeSymbolID
	Name       string
	Kind       SymbolKind
	Location   SymbolLocation
	Scope      *SymbolScope
	IsExported bool
	IsExternal bool

	// Language-specific metadata
	Language       string
	Signature      string             // Function/method signature
	Type           string             // Variable/field type
	Value          string             // Constant value if applicable
	TypeParameters []TypeParameter    `json:"type_parameters,omitempty"` // Generic type parameters
	Attributes     []ContextAttribute `json:"attributes,omitempty"`      // Decorators, attributes, annotations

	// Relationships
	ParentSymbol    *CompositeSymbolID  // For methods, fields, etc.
	ImplementsIDs   []CompositeSymbolID // Interfaces this type implements
	ReferencedByIDs []CompositeSymbolID // Symbols that reference this one
	ReferencesIDs   []CompositeSymbolID // Symbols this one references
}

type EnhancedTrigram struct {
	Type     TrigramType
	ByteHash uint32 // For byte-based trigrams (ASCII content)
	RuneStr  string // For rune-based trigrams (Unicode content)
	RuneHash uint64 // Hash of the rune string for indexing
}

type ErrorHandlingInfo struct {
	// Can the function throw/panic?
	CanThrow bool

	// Does it return errors? (Go pattern)
	ReturnsError bool

	// Exception safety level
	ExceptionNeutral bool // No cleanup needed (no resources acquired)
	ExceptionSafe    bool // Cleanup guaranteed (defer, try-finally present)

	// Details
	DeferCount       int   // Number of defer statements
	TryFinallyCount  int   // Number of try-finally blocks
	ThrowCount       int   // Number of throw/panic sites
	ErrorReturnLines []int // Lines with error returns
}

type ExpansionDirective struct {
	Type  string // "callers", "callees", "implementations", etc.
	Depth int    // For "callers:2", depth is 2. Default is 1.
}

type ExportInfo struct {
	LocalID      uint32 // Local symbol ID for this export
	ExportedName string // Name as exported
	LocalName    string // Local name (might be different)
	IsDefault    bool   // True for default export
	IsTypeOnly   bool   // True for TypeScript type-only exports
	IsReExport   bool   // True if re-exporting from another module
	SourcePath   string // Source module for re-exports
	Location     SymbolLocation
}

type ExternalCallInfo struct {
	FunctionName string
	Line         int
	Column       int
	IsMethod     bool
	ReceiverType string // For method calls
	Package      string // If determinable
	Reason       string // Why it's considered external
}

type FieldAccess struct {
	// What is being accessed (canonical form: "param:user.Name", "global:counter")
	Target string

	// Classification of the target
	TargetType AccessTarget

	// Read or write
	Type AccessType

	// Location in source
	Line   int
	Column int

	// Order within function (0, 1, 2, ...) for sequence analysis
	SeqNum int

	// The base identifier (e.g., "user" in "user.Name")
	BaseIdentifier string

	// Field path (e.g., ["Name"] in "user.Name", ["addr", "city"] in "user.addr.city")
	FieldPath []string
}

type FileID uint32

type FileInfo struct {
	ID   FileID
	Path string
	// Content is now managed by FileContentStore - access via ID
	LastModified    time.Time
	Checksum        uint64
	FastHash        uint64   // xxhash for quick equality checks (~0.5ns)
	ContentHash     [32]byte // Pre-computed SHA256 hash for cache optimization
	Blocks          []BlockBoundary
	EnhancedSymbols []*EnhancedSymbol // All symbols with relational data (pointers avoid copy overhead)
	Imports         []Import
	References      []Reference           // All references in this file
	ScopeHierarchy  []ScopeInfo           // Complete scope chain for file
	CharMask        EnhancedCharacterMask // Enhanced character mask with ASCII bitmask + Unicode bloom filter

	// Performance optimization: Precomputed line boundaries for O(1) line access
	// LineOffsets[i] contains the byte offset of the start of line i+1
	// Example: LineOffsets = [0, 10, 25] means line 1 starts at 0, line 2 at 10, line 3 at 25
	LineOffsets []int `json:"-"` // Computed during indexing

	// Performance optimization: Pre-computed line->symbol index for O(1) semantic filtering
	// LineToSymbols[line] contains indices into EnhancedSymbols for symbols on that line
	// Avoids O(symbols) scan per search match by moving to O(1) lookup
	LineToSymbols map[int][]int `json:"-"` // Computed during indexing

	// Performance analysis data collected during AST parsing
	// Used for detecting performance anti-patterns (sequential awaits, expensive calls in loops, etc.)
	PerfData []FunctionPerfData `json:"perf_data,omitempty"`

	// Deprecated: Remove after migration to FileContentStore
	Content []byte   `json:"-"` // Will be removed
	Lines   []string `json:"-"` // Will be removed
}

type FilePathIndex struct {
	// Path segments indexed by depth for efficient glob matching
	// Example: "internal/tui/views/main.go" -> segments[0]["internal"], segments[1]["tui"], segments[2]["views"]
	PathSegments map[int]map[string][]FileID `json:"path_segments"` // depth -> segment -> FileIDs

	// Full paths for exact matching and fallback
	FullPaths map[FileID]string `json:"full_paths"` // FileID -> full path

	// File extensions for filtering
	Extensions map[string][]FileID `json:"extensions"` // extension (e.g., ".go") -> FileIDs

	// Directory hierarchy for efficient directory-based searches
	Directories map[string][]FileID `json:"directories"` // directory path -> FileIDs

	// Base filenames for pattern matching
	BaseNames map[string][]FileID `json:"base_names"` // filename without path -> FileIDs

	// File count for statistics
	TotalFiles int `json:"total_files"`
}

type FileSearchOptions struct {
	Pattern     string   `json:"pattern"`     // Glob pattern like "internal/tui/*view*.go"
	Type        string   `json:"type"`        // "glob", "regex", or "exact"
	Exclude     []string `json:"exclude"`     // Patterns to exclude
	MaxResults  int      `json:"max_results"` // Maximum results to return (default: 100)
	Extensions  []string `json:"extensions"`  // File extensions to include (e.g., [".go", ".ts"])
	Directories []string `json:"directories"` // Directory patterns to search in
}

type FileSearchResult struct {
	FileID      FileID `json:"file_id"`
	Path        string `json:"path"`
	Directory   string `json:"directory"`
	BaseName    string `json:"base_name"`
	Extension   string `json:"extension"`
	Language    string `json:"language"`     // Programming language based on extension
	MatchReason string `json:"match_reason"` // How the pattern matched
}

type FormatType string

type FunctionCall struct {
	Target      CompositeSymbolID `json:"target"`       // Function being called
	CallType    CallType          `json:"call_type"`    // Type of call
	Location    SymbolLocation    `json:"location"`     // Where call occurs
	Context     string            `json:"context"`      // Context of the call
	IsAsync     bool              `json:"is_async"`     // Whether call is asynchronous
	IsRecursive bool              `json:"is_recursive"` // Whether call is recursive
	Arguments   []CallArgument    `json:"arguments"`    // Arguments passed (if available)
}

type FunctionContext struct {
	Name        string `json:"name"`
	Qualified   string `json:"qualified"`
	StartLine   int    `json:"start_line"`
	EndLine     int    `json:"end_line"`
	Known       bool   `json:"known"`    // False if no enclosing function
	Inferred    bool   `json:"inferred"` // True if resolved heuristically, not from scope hierarchy
	Description string `json:"description,omitempty"`
}

type FunctionPerfData struct {
	Name      string      `json:"name"`
	StartLine int         `json:"start_line"`
	EndLine   int         `json:"end_line"`
	IsAsync   bool        `json:"is_async"`
	Language  string      `json:"language"`
	Loops     []LoopData  `json:"loops,omitempty"`
	Awaits    []AwaitData `json:"awaits,omitempty"`
	Calls     []CallData  `json:"calls,omitempty"`
}

type FunctionTree struct {
	RootFunction string      `json:"root_function"`
	Root         *TreeNode   `json:"root"`
	MaxDepth     int         `json:"max_depth"`
	TotalNodes   int         `json:"total_nodes"`
	Options      TreeOptions `json:"options"`
}

type GlobalWriteInfo struct {
	GlobalName string
	Line       int
	Column     int
	FieldPath  []string
	IsPackage  bool // Package-level vs module-level
}

type HotSpot struct {
	File       string `json:"file"`
	MatchCount int    `json:"match_count"`
	FirstLine  int    `json:"first_line"`
	LastLine   int    `json:"last_line"`
}

type HydratedContext struct {
	// Task from manifest
	Task string `json:"task,omitempty"`

	// Hydrated references with source code
	Refs []HydratedRef `json:"refs"`

	// Hydration statistics
	Stats HydrationStats `json:"stats"`

	// Warnings (e.g., missing symbols, truncation)
	Warnings []string `json:"warnings,omitempty"`
}

type HydratedRef struct {
	// Location
	File   string    `json:"file"`
	Symbol string    `json:"symbol,omitempty"`
	Lines  LineRange `json:"lines"`

	// Metadata from manifest (passed through from ContextRef)
	Role string `json:"role,omitempty"`
	Note string `json:"note,omitempty"`

	// Hydrated content
	Source string `json:"source"` // Actual source code

	// Symbol metadata (when available)
	SymbolType string `json:"symbol_type,omitempty"` // "function", "class", "method", etc.
	Signature  string `json:"signature,omitempty"`   // Function/method signature

	// Expanded relationships (based on directives in X)
	Expanded map[string][]HydratedRef `json:"expanded,omitempty"`

	// Context quality indicators
	IsExported  bool `json:"is_exported,omitempty"`
	IsGenerated bool `json:"is_generated,omitempty"` // Generated code (warn agent)

	// Purity analysis (for callees/dependencies)
	Purity     *PurityInfo `json:"purity,omitempty"`      // Purity info for this symbol
	IsExternal bool        `json:"is_external,omitempty"` // True if external dependency (not in codebase)
}

type HydrationStats struct {
	RefsLoaded        int  `json:"refs_loaded"`         // Number of refs from manifest
	SymbolsHydrated   int  `json:"symbols_hydrated"`    // Total symbols (including expansions)
	TokensApprox      int  `json:"tokens_approx"`       // Approximate token count
	ExpansionsApplied int  `json:"expansions_applied"`  // Number of expansions executed
	Truncated         bool `json:"truncated,omitempty"` // Whether results were truncated
}

type Import struct {
	Path   string
	FileID FileID
	Line   int
}

type ImportInfo struct {
	LocalID       uint32   // Local symbol ID for this import
	ImportPath    string   // What is being imported
	Alias         string   // Import alias if any
	ImportedNames []string // Specific names imported (for named imports)
	IsDefault     bool     // True for default imports
	IsNamespace   bool     // True for namespace imports (import * as X)
	IsTypeOnly    bool     // True for TypeScript type-only imports
	Location      SymbolLocation
}

type IntentAnalysisOptions struct {
	Intent          string   `json:"intent"`           // Specific intent to search for (e.g., "size_management", "event_handling")
	Scope           string   `json:"scope"`            // File scope to analyze (glob patterns like "**/ui/**")
	Context         string   `json:"context"`          // Domain context ("ui", "api", "business-logic", "configuration")
	AntiPatterns    []string `json:"anti_patterns"`    // Specific anti-patterns to detect or "*" for all
	MinConfidence   float64  `json:"min_confidence"`   // Minimum confidence threshold (0.0-1.0, default: 0.5)
	IncludeEvidence bool     `json:"include_evidence"` // Include code evidence in results (default: true)
	MaxResults      int      `json:"max_results"`      // Maximum results to return (default: 50)
}

type KnownIOFunction struct {
	Package  string
	Function string
	Language string
	IOType   SideEffectCategory // SideEffectIO, SideEffectNetwork, etc.
}

type KnownPureFunction struct {
	Package  string // e.g., "strings", "math", "fmt"
	Function string // e.g., "ToLower", "Sqrt"
	Language string // e.g., "go", "javascript", "python"
}

type LineRange struct {
	Start int `json:"s"` // Start line (1-indexed)
	End   int `json:"e"` // End line (1-indexed, inclusive)
}

type LoadParams struct {
	// Where to load from
	FromFile   string `json:"from_file,omitempty"`   // File path (relative to project root)
	FromString string `json:"from_string,omitempty"` // Inline JSON string

	// What to include
	Filter  []string `json:"filter,omitempty"`  // Only include these roles
	Exclude []string `json:"exclude,omitempty"` // Exclude these roles

	// Output control
	Format    string `json:"format,omitempty"`     // "full" (default), "signatures", "outline"
	MaxTokens int    `json:"max_tokens,omitempty"` // Approximate token limit (0 = no limit)
}

type LoopData struct {
	NodeType  string `json:"node_type"` // "for_statement", "while_statement", etc.
	StartLine int    `json:"start_line"`
	EndLine   int    `json:"end_line"`
	Depth     int    `json:"depth"` // Nesting depth (1 = top-level loop)
}

type ManifestStats struct {
	RefCount      int            `json:"rc"`           // Number of refs
	TotalLines    int            `json:"tl,omitempty"` // Total lines referenced (approximate)
	FileCount     int            `json:"fc,omitempty"` // Unique files
	RoleBreakdown map[string]int `json:"rb,omitempty"` // Role → count
	SizeBytes     int            `json:"sb,omitempty"` // Manifest file size in bytes
}

type ModuleResolution struct {
	RequestPath  string // Original import/require path
	ResolvedPath string // Resolved file path
	FileID       FileID // Resolved file ID
	IsExternal   bool   // True if outside indexed folder
	IsBuiltin    bool   // True for language builtins
	Resolution   ResolutionType
	Error        string // Error message if resolution failed
}

type MultiSearchStats struct {
	Patterns []string                `json:"patterns"`
	Results  map[string]*SearchStats `json:"results"`

	// Cross-pattern analysis
	CommonFiles       []string                  `json:"common_files"`  // Files matching all patterns
	CoOccurrence      map[string]map[string]int `json:"co_occurrence"` // Pattern pairs -> count
	TotalSearchTimeMs int64                     `json:"total_search_time_ms"`
}

type NodeAnnotation struct {
	Type        NodeType               `json:"type"`
	Emoji       string                 `json:"emoji"`
	Description string                 `json:"description"`
	Metadata    map[string]interface{} `json:"metadata,omitempty"` // iterations, probability, timing, etc.
}

type NodeType uint8

type ParameterWriteInfo struct {
	ParameterName  string
	ParameterIndex int
	Line           int
	Column         int
	FieldPath      []string // Empty for direct write, populated for field access
	IsPointer      bool     // Write through pointer dereference
}

type PatternVerificationOptions struct {
	Pattern    string   `json:"pattern"`     // Pattern name (built-in) or custom rule
	Scope      string   `json:"scope"`       // File pattern scope for verification
	Severity   []string `json:"severity"`    // Filter by severity levels (error, warning, info)
	MaxResults int      `json:"max_results"` // Maximum violations to return
	ReportMode string   `json:"report_mode"` // 'violations' or 'summary' or 'detailed'
}

type PatternViolation struct {
	Type ViolationType

	// The target involved
	Target string

	// Location information
	Line      int // Primary line (usually the problematic access)
	ReadLine  int // Line of the read involved
	WriteLine int // Line of the write involved

	// Human-readable description
	Description string

	// Severity from 0.0 (informational) to 1.0 (definitely problematic)
	Severity float64
}

type PurityClassification struct {
	// Parameters mutated (vector of parameter indices)
	// e.g., [0, 2] means parameters 0 and 2 are mutated
	MutatedParameters []int

	// Object/receiver mutated
	MutatesReceiver bool

	// Globals mutated (list of global variable names)
	MutatedGlobals []string

	// Closures mutated (list of captured variable names)
	MutatedClosures []string

	// Dependent functions and their purity status
	// Maps function name to its purity (true = pure, false = impure)
	DependentFunctions map[string]bool

	// I/O operations performed
	PerformsIO bool

	// Network operations performed
	PerformsNetwork bool

	// Database operations performed
	PerformsDatabase bool

	// Exception/panic operations
	CanThrow bool
}

type PurityConfidence uint8

type PurityInfo struct {
	IsPure      bool     `json:"is_pure"`                // True if function has no side effects
	PurityLevel string   `json:"purity_level,omitempty"` // "Pure", "InternallyPure", "ObjectState", "ModuleGlobal", "ExternalDependency"
	Categories  []string `json:"categories,omitempty"`   // Side effect categories (e.g., "io", "param_write")
	PurityScore float64  `json:"purity_score,omitempty"` // 0.0-1.0
	Reasons     []string `json:"reasons,omitempty"`      // Why it's impure
}

type PurityLevel int

type RefCount struct {
	IncomingCount int              `json:"incoming_count"`
	OutgoingCount int              `json:"outgoing_count"`
	IncomingFiles []FileID         `json:"incoming_files"`
	OutgoingFiles []FileID         `json:"outgoing_files"`
	ByType        map[string]int   `json:"by_type"`
	Strength      RefStrengthStats `json:"strength"`
}

type RefStats struct {
	FolderLevel   RefCount `json:"folder_level"`
	FileLevel     RefCount `json:"file_level"`
	ClassLevel    RefCount `json:"class_level"`
	FunctionLevel RefCount `json:"function_level"`
	VariableLevel RefCount `json:"variable_level"`
	Total         RefCount `json:"total"`
}

type RefStrength uint8

type RefStrengthStats struct {
	Tight      int `json:"tight"`
	Loose      int `json:"loose"`
	Transitive int `json:"transitive"`
}

type Reference struct {
	ID             uint64        `json:"id"`
	SourceSymbol   SymbolID      `json:"source_symbol"`
	TargetSymbol   SymbolID      `json:"target_symbol"`
	FileID         FileID        `json:"file_id"`
	Line           int           `json:"line"`
	Column         int           `json:"column"`
	Type           ReferenceType `json:"type"`
	ContextLines   []StringRef   `json:"-"`             // Line references for context (not serialized)
	ScopeContext   []ScopeInfo   `json:"scope_context"` // Scope breadcrumb at reference point
	Strength       RefStrength   `json:"strength"`
	ReferencedName string        `json:"referenced_name"`          // Actual symbol name being referenced (from Tree-sitter AST)
	Quality        string        `json:"quality,omitempty"`        // RefQuality* constants: precise, assigned, returned, cast, heuristic
	Resolved       *bool         `json:"resolved,omitempty"`       // For include/import resolution (nil if not applicable)
	Ambiguous      bool          `json:"ambiguous,omitempty"`      // Multiple possible targets
	Candidates     []string      `json:"candidates,omitempty"`     // Candidate file paths / symbols for ambiguous include
	FailureReason  string        `json:"failure_reason,omitempty"` // If Resolved=false

	// Deprecated
	Context []string `json:"context"` // Will be removed
}

type ReferenceType uint8

type RelatedSymbol struct {
	Symbol   EnhancedSymbol `json:"symbol"`
	Relation RelationType   `json:"relation"`
	Strength RefStrength    `json:"strength"`
	Distance int            `json:"distance"`            // Degrees of separation
	FileName string         `json:"file_name,omitempty"` // File name for display
}

type RelationType uint8

type RelationalContext struct {
	Symbol         EnhancedSymbol  `json:"symbol"`
	RefStats       RefStats        `json:"ref_stats"`
	Breadcrumbs    []ScopeInfo     `json:"breadcrumbs"`      // Scope chain outside search context
	RelatedSymbols []RelatedSymbol `json:"related_symbols"`  // Nearby related symbols
	Function       FunctionContext `json:"function_context"` // Enclosing function/method context
}

type RelationshipType uint8

type ResolutionType int

type SaveParams struct {
	// What to save
	Refs []ContextRef `json:"refs,omitempty"` // References to save

	// Where to save
	ToFile   string `json:"to_file,omitempty"`   // File path (relative to project root)
	ToString bool   `json:"to_string,omitempty"` // Return as JSON string instead of writing

	// How to save
	Append bool   `json:"append,omitempty"` // Merge with existing manifest (default: false)
	Task   string `json:"task,omitempty"`   // Task description/directive
}

type SaveResponse struct {
	Saved     string        `json:"saved,omitempty"`    // File path if to_file was used
	Manifest  string        `json:"manifest,omitempty"` // JSON string if to_string was true
	Stats     ManifestStats `json:"stats"`
	RefCount  int           `json:"ref_count"`  // Number of refs saved
	FileCount int           `json:"file_count"` // Number of unique files
}

type ScopeInfo struct {
	Type       ScopeType          `json:"type"`
	Name       string             `json:"name"`
	FullPath   string             `json:"full_path"`
	StartLine  int                `json:"start_line"`
	EndLine    int                `json:"end_line"`
	Level      int                `json:"level"`
	Language   string             `json:"language"`
	Attributes []ContextAttribute `json:"attributes,omitempty"` // Context attributes for this scope
}

type ScopeType uint8

type SearchOptions struct {
	// Basic search options
	CaseInsensitive    bool
	MaxContextLines    int
	MergeFileResults   bool   // Merge multiple results from same file
	EnsureCompleteStmt bool   // Ensure complete statements with comments
	ExcludePattern     string // Regex pattern to exclude files
	IncludePattern     string // Regex pattern to include files (whitelist)

	// Result control
	MaxResults int // Optional cap for number of results to return (0 = no cap)

	// Regex support
	UseRegex bool // Enable regex pattern matching

	// Semantic search filters for AI agents
	SymbolTypes     []string // Filter by symbol types: "function", "variable", "class", "type", "constant"
	DeclarationOnly bool     // Only show symbol definitions, not usages
	UsageOnly       bool     // Only show symbol usages, not definitions
	ExportedOnly    bool     // Only show public/exported symbols
	ExcludeTests    bool     // Exclude test files and test functions
	ExcludeComments bool     // Exclude matches in comments (deprecated: use CodeOnly instead)
	MutableOnly     bool     // Only mutable variables (var, not const)
	GlobalOnly      bool     // Only global/package-level symbols

	// Content-specific filters (powered by AST)
	CommentsOnly    bool // Search only in comments
	CodeOnly        bool // Search only in code (excludes comments and strings)
	StringsOnly     bool // Search only in string literals
	TemplateStrings bool // Include template strings (sql“, gql“, etc.) when StringsOnly is true

	// Context extraction control
	FullFunction     bool // Show complete function body for matches inside functions
	MaxFunctionLines int  // Max lines for function context (0 = unlimited)
	ContextPadding   int  // Extra lines around match when not showing full function

	// Grep-like features (P0 - Critical for LLM use cases)
	InvertMatch     bool     // Inverted match (grep -v): show lines that DON'T match pattern
	Patterns        []string // Multiple patterns with OR logic (grep -e pattern1 -e pattern2)
	CountPerFile    bool     // Return match count per file (grep -c)
	FilesOnly       bool     // Return only filenames with matches (grep -l)
	WordBoundary    bool     // Match whole words only (grep -w)
	MaxCountPerFile int      // Max matches per file (grep -m), 0 = unlimited

	// Additional indexing-specific option
	Verbose bool // Show verbose output
	// Context search option
	IncludeObjectIDs bool // Include compact object IDs for context search (default: true)

	// AI-focused features for RepoBench evaluation
	ContextFilter string // Filter results by context pattern (e.g., "cache", "test")
}

type SearchStats struct {
	Pattern          string `json:"pattern"`
	TotalMatches     int    `json:"total_matches"`
	FilesWithMatches int    `json:"files_with_matches"`

	// Distribution across codebase
	FileDistribution map[string]int `json:"file_distribution"` // filepath -> match count
	DirDistribution  map[string]int `json:"dir_distribution"`  // directory -> match count

	// Symbol context
	SymbolTypes     map[string]int `json:"symbol_types"` // "function", "variable", etc -> count
	DefinitionCount int            `json:"definition_count"`
	UsageCount      int            `json:"usage_count"`
	CommentMatches  int            `json:"comment_matches"`

	// Code quality indicators
	TestFileMatches int `json:"test_file_matches"`
	ExportedSymbols int `json:"exported_symbols"`

	// Performance hints
	HotSpots     []HotSpot `json:"hot_spots"` // Files with most matches
	SearchTimeMs int64     `json:"search_time_ms"`
}

type SideEffectCategory uint32

type SideEffectInfo struct {
	// Function identification
	FunctionName string
	FilePath     string
	StartLine    int
	EndLine      int

	// Bitfield of detected side effect categories
	Categories SideEffectCategory

	// Confidence in the analysis
	Confidence PurityConfidence

	// Purity level (two-phase analysis result)
	PurityLevel PurityLevel

	// Purity classification: track WHAT affects purity
	PurityClassification PurityClassification

	// Access pattern analysis
	AccessPattern *AccessPattern

	// Specific details about detected effects
	ParameterWrites []ParameterWriteInfo
	GlobalWrites    []GlobalWriteInfo
	ExternalCalls   []ExternalCallInfo
	ThrowSites      []ThrowSiteInfo

	// Unresolved function calls (for Phase 2 propagation)
	UnresolvedCalls []UnresolvedCallInfo

	// Error handling analysis
	ErrorHandling *ErrorHandlingInfo

	// Transitive effects (from callees) - populated by propagation
	TransitiveCategories SideEffectCategory
	TransitiveConfidence PurityConfidence

	// Combined assessment
	IsPure           bool    // True ONLY if locally pure AND all callees pure
	PurityScore      float64 // 1.0 = definitely pure, 0.0 = definitely impure
	PurityConfidence float64 // Confidence in the purity score (0.0-1.0)

	// Reasons for impurity (for debugging/reporting)
	ImpurityReasons []string
}

type StringRef struct {
	FileID FileID // Which file this string comes from
	Offset uint32 // Byte offset in the file
	Length uint32 // Number of bytes
	Hash   uint64 // Precomputed hash of the string content
}

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

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

type Symbol struct {
	Name           string
	Type           SymbolType
	FileID         FileID
	Line           int
	Column         int
	EndLine        int
	EndColumn      int
	Attributes     []ContextAttribute // Context-altering attributes
	TypeParameters []TypeParameter    `json:"type_parameters,omitempty"` // Generic type parameters
	Visibility     SymbolVisibility   `json:"visibility,omitempty"`      // Visibility/export status
}

type SymbolAnnotation struct {
	Type       AnnotationType `json:"type"`       // Type of annotation
	Value      string         `json:"value"`      // Annotation value
	Parameters []string       `json:"parameters"` // Annotation parameters
	Location   SymbolLocation `json:"location"`   // Where annotation appears
}

type SymbolDependency struct {
	Target        CompositeSymbolID  `json:"target"`         // What this symbol depends on
	Type          DependencyType     `json:"type"`           // Type of dependency
	Strength      DependencyStrength `json:"strength"`       // How strong the dependency is
	Context       string             `json:"context"`        // Context where dependency occurs
	ImportPath    string             `json:"import_path"`    // Import path if applicable
	IsOptional    bool               `json:"is_optional"`    // Whether dependency is optional
	IsConditional bool               `json:"is_conditional"` // Whether dependency is conditional
}

type SymbolID uint64

type SymbolIdentity struct {
	ID        CompositeSymbolID `json:"id"`        // Unique composite ID
	Name      string            `json:"name"`      // Symbol name
	FullName  string            `json:"full_name"` // Fully qualified name
	Kind      SymbolKind        `json:"kind"`      // Type of symbol (function, class, etc.)
	Language  string            `json:"language"`  // Programming language
	Location  SymbolLocation    `json:"location"`  // Where the symbol is defined
	Signature string            `json:"signature"` // Function/method signature
	Type      string            `json:"type"`      // Variable/field type
	Value     string            `json:"value"`     // Constant value if applicable
}

type SymbolKind int

type SymbolLocation struct {
	FileID FileID
	Line   int
	Column int
	Offset int // Byte offset in file
}

type SymbolMetadata struct {
	// Documentation and comments
	Documentation []string `json:"documentation"` // Doc comments
	Comments      []string `json:"comments"`      // Inline comments

	// Attributes and annotations
	Attributes  []ContextAttribute `json:"attributes"`  // Context attributes (async, deprecated, etc.)
	Annotations []SymbolAnnotation `json:"annotations"` // Language-specific annotations

	// Quality metrics
	ComplexityScore int `json:"complexity_score"` // Cyclomatic/cognitive complexity
	CouplingScore   int `json:"coupling_score"`   // How tightly coupled this symbol is
	CohesionScore   int `json:"cohesion_score"`   // How cohesive this symbol is

	// AI navigation hints
	EditRiskScore int      `json:"edit_risk_score"` // Risk of editing this symbol (0-10)
	StabilityTags []string `json:"stability_tags"`  // CORE, PUBLIC_API, RECURSIVE, etc.
	SafetyNotes   []string `json:"safety_notes"`    // Human-readable safety warnings
}

type SymbolReference struct {
	Symbol     CompositeSymbolID // The symbol being referenced
	Location   SymbolLocation    // Where the reference occurs
	IsExternal bool              // True if the symbol is external to the indexed folder
	ImportPath string            // Import path if applicable (e.g., "fmt", "react")
}

type SymbolRelationships struct {
	// Structural relationships
	Extends     []CompositeSymbolID `json:"extends"`      // Types this symbol extends
	Implements  []CompositeSymbolID `json:"implements"`   // Interfaces this symbol implements
	Contains    []CompositeSymbolID `json:"contains"`     // Symbols contained within this symbol
	ContainedBy *CompositeSymbolID  `json:"contained_by"` // Parent symbol containing this one

	// Dependency relationships
	Dependencies []SymbolDependency  `json:"dependencies"` // Symbols this depends on
	Dependents   []CompositeSymbolID `json:"dependents"`   // Symbols that depend on this

	// Call relationships (from existing CallGraph)
	CallsTo  []FunctionCall `json:"calls_to"`  // Functions this calls
	CalledBy []FunctionCall `json:"called_by"` // Functions that call this

	// File co-location relationships
	FileCoLocated []CompositeSymbolID `json:"file_co_located"` // Other symbols in same file

	// Cross-language relationships
	CrossLanguage []CrossLanguageLink `json:"cross_language"` // Links to symbols in other languages
}

type SymbolScope struct {
	Type     SymbolScopeType
	Name     string // Name of the scope (e.g., function name, class name)
	Parent   *SymbolScope
	StartPos int // Start position in file
	EndPos   int // End position in file
}

type SymbolScopeType int

type SymbolTable struct {
	FileID   FileID
	Language string
	Symbols  map[uint32]*EnhancedSymbolInfo // LocalSymbolID -> Symbol
	Imports  []ImportInfo
	Exports  []ExportInfo

	// Scope tree
	RootScope *SymbolScope

	// Quick lookups
	SymbolsByName map[string][]uint32 // Name -> LocalSymbolIDs
	NextLocalID   uint32              // Next available LocalSymbolID
}

type SymbolType uint8

type SymbolUsage struct {
	ReferenceCount    int `json:"reference_count"`    // Total references to this symbol
	ImportCount       int `json:"import_count"`       // Times imported
	InheritanceCount  int `json:"inheritance_count"`  // Times extended/implemented
	CallCount         int `json:"call_count"`         // Times called (functions only)
	ModificationCount int `json:"modification_count"` // Times modified (variables only)

	// Reference patterns
	ReferencingFiles []FileID       `json:"referencing_files"` // Files that reference this
	HotSpots         []UsageHotSpot `json:"hot_spots"`         // High-usage locations

	// Temporal usage patterns
	FirstSeen      time.Time `json:"first_seen"`      // When first discovered
	LastModified   time.Time `json:"last_modified"`   // Last modification time
	LastReferenced time.Time `json:"last_referenced"` // Last time referenced
}

type SymbolVisibility struct {
	Access      AccessLevel `json:"access"`       // public, private, protected, internal
	Scope       SymbolScope `json:"scope"`        // Scope hierarchy information
	IsExported  bool        `json:"is_exported"`  // Whether symbol is exported/public
	IsExternal  bool        `json:"is_external"`  // Whether symbol is external to project
	IsBuiltin   bool        `json:"is_builtin"`   // Whether symbol is language builtin
	IsGenerated bool        `json:"is_generated"` // Whether symbol is generated code
}

type TargetAccessPattern struct {
	// The target being accessed
	Target string

	// Classification of the target
	TargetType AccessTarget

	// Pattern for this specific target
	Pattern AccessPatternType

	// Access counts
	ReadCount  int
	WriteCount int

	// Sequence string: "RRW" = read, read, write; "WRR" = write, read, read
	Sequence string

	// Lines of first read and first write (for violation reporting)
	FirstReadLine  int
	FirstWriteLine int

	// Line of first read after a write (for WriteThenRead detection)
	FirstReadAfterWriteLine int
}

type ThrowSiteInfo struct {
	Type   string // "panic", "throw", "raise", etc.
	Line   int
	Column int
}

type TreeNode struct {
	Name        string           `json:"name"`
	FilePath    string           `json:"file_path"`
	Line        int              `json:"line"`
	Depth       int              `json:"depth"`
	NodeType    NodeType         `json:"node_type"`
	Annotations []NodeAnnotation `json:"annotations"`
	Children    []*TreeNode      `json:"children"`
	Parent      *TreeNode        `json:"-"` // Exclude from JSON to avoid circular references

	// Edit safety and stability indicators for coding agents
	EditRiskScore   int      `json:"edit_risk_score"`  // 0-10 risk of breaking when editing this function
	StabilityTags   []string `json:"stability_tags"`   // CORE, PUBLIC_API, RECURSIVE, SIDE_EFFECTS, FRAGILE
	DependencyCount int      `json:"dependency_count"` // Number of functions this depends on
	DependentCount  int      `json:"dependent_count"`  // Number of functions that depend on this
	ImpactRadius    int      `json:"impact_radius"`    // How many files could be affected by changes
	SafetyNotes     []string `json:"safety_notes"`     // Human-readable safety warnings
}

type TreeOptions struct {
	MaxDepth       int    `json:"max_depth"`
	ShowLines      bool   `json:"show_lines"`
	Compact        bool   `json:"compact"`
	ExcludePattern string `json:"exclude_pattern"`
	AgentMode      bool   `json:"agent_mode"`
}

type TrigramType uint8

type TypeParameter struct {
	Name       string `json:"name"`       // e.g., "T", "K", "V"
	Constraint string `json:"constraint"` // e.g., "any", "comparable", "io.Reader"
}

type UniversalSymbolNode struct {
	// Identity - Core identification information
	Identity SymbolIdentity `json:"identity"`

	// Relationships - All types of relationships this symbol has
	Relationships SymbolRelationships `json:"relationships"`

	// Visibility - Access control and scope information
	Visibility SymbolVisibility `json:"visibility"`

	// Usage - Usage statistics and metrics
	Usage SymbolUsage `json:"usage"`

	// Metadata - Additional contextual information
	Metadata SymbolMetadata `json:"metadata"`
}

type UnresolvedCallInfo struct {
	FunctionName string
	Qualifier    string // Package/module or receiver type
	IsMethod     bool
	Line         int
	Column       int
}

type UsageHotSpot struct {
	FileID     FileID  `json:"file_id"`     // File with high usage
	StartLine  int     `json:"start_line"`  // Start of hot spot region
	EndLine    int     `json:"end_line"`    // End of hot spot region
	UsageCount int     `json:"usage_count"` // Number of usages in region
	UsageType  string  `json:"usage_type"`  // Type of usage (calls, references, etc.)
	Intensity  float64 `json:"intensity"`   // Usage intensity score
}

type ValidationError struct {
	Field   string
	Message string
}

type VariableType uint8

type ViolationType uint8

type ZeroAllocStringRef struct {
	Data   []byte // Direct reference to the byte data (no allocation)
	FileID FileID // For safety and LRU tracking
	Offset uint32 // Offset within the data slice
	Length uint32 // Length of the string reference
	Hash   uint64 // Precomputed hash for fast equality
}

type ZeroAllocStringRefSlice []ZeroAllocStringRef