codetypes

type APIAnalyzer interface {
	AnalyzeAPIPaths(paths []string) ([]APIChunk, error)
}

type APIChunk struct {
	// Identification
	Kind     string `json:"kind"` // function | method | type | const | var | class | interface
	Name     string `json:"name"`
	Language string `json:"language"` // go | php | python | typescript etc

	// Location
	PackagePath string `json:"package_path,omitempty"`
	Package     string `json:"package"`
	FilePath    string `json:"file_path,omitempty"`
	URI         string `json:"uri,omitempty"` // Full document URI
	StartLine   int    `json:"start_line,omitempty"`
	EndLine     int    `json:"end_line,omitempty"`

	// Selection range (for precise navigation to symbol name)
	SelectionStartLine int `json:"selection_start_line,omitempty"`
	SelectionEndLine   int `json:"selection_end_line,omitempty"`

	// Content & Documentation
	Signature   string `json:"signature,omitempty"`
	Description string `json:"description,omitempty"`
	Detail      string `json:"detail,omitempty"` // Short additional info
	Code        string `json:"code,omitempty"`

	// Function/Method specific
	Parameters []ParamInfo  `json:"parameters,omitempty"`
	Returns    []ReturnInfo `json:"returns,omitempty"`
	Receiver   string       `json:"receiver,omitempty"`
	Examples   []string     `json:"examples,omitempty"`

	// Type specific
	Fields  []FieldInfo  `json:"fields,omitempty"`
	Methods []MethodInfo `json:"methods,omitempty"`

	// Const/Var specific
	DataType string `json:"data_type,omitempty"`
	Value    string `json:"value,omitempty"`

	// Metadata & Attributes
	IsExported     bool     `json:"is_exported"`
	AccessModifier string   `json:"access_modifier,omitempty"` // public | private | protected | internal
	Tags           []string `json:"tags,omitempty"`            // deprecated | experimental | internal
	Deprecated     bool     `json:"deprecated,omitempty"`
	ContainerName  string   `json:"container_name,omitempty"` // Parent class/module name

	// Hierarchy support (for nested symbols)
	Children []APIChunk `json:"children,omitempty"`
}

type ClassDescriptor struct {
	Language string `json:"language"`
	Kind     string `json:"kind"` // class | interface | trait | struct | type | model
	Name     string `json:"name"`

	Namespace string `json:"namespace,omitempty"`
	Package   string `json:"package,omitempty"`
	FullName  string `json:"full_name,omitempty"`

	Signature   string         `json:"signature,omitempty"`
	Description string         `json:"description,omitempty"`
	Location    SymbolLocation `json:"location,omitempty"`

	Fields    []FieldDescriptor    `json:"fields,omitempty"`
	Methods   []FunctionDescriptor `json:"methods,omitempty"`
	Relations []RelationDescriptor `json:"relations,omitempty"`

	// Data-model specific (used by ORMs like Eloquent, but generic enough for others)
	Table      string            `json:"table,omitempty"`
	Fillable   []string          `json:"fillable,omitempty"`
	Hidden     []string          `json:"hidden,omitempty"`
	Visible    []string          `json:"visible,omitempty"`
	Appends    []string          `json:"appends,omitempty"`
	Casts      map[string]string `json:"casts,omitempty"`
	Scopes     []string          `json:"scopes,omitempty"`
	Attributes []string          `json:"attributes,omitempty"`

	Tags     []string       `json:"tags,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type CodeChunk struct {
	// Symbol metadata
	Type     string // function | method | type | interface | file
	Name     string // Symbol name (or file base name for Type=file)
	Package  string // Package/module name
	Language string // go | php | python | typescript etc

	// Source location
	FilePath  string // Relative path from repository root
	URI       string // Full document URI (optional)
	StartLine int    // 1-based
	EndLine   int    // 1-based

	// Selection range (for precise navigation to symbol name)
	SelectionStartLine int // 1-based line where symbol name starts
	SelectionEndLine   int // 1-based line where symbol name ends

	// Content
	Signature string // Function/method signature or type definition header
	Docstring string // Associated doc comment (trimmed)
	Code      string // Pretty-printed code for this chunk

	// Extra metadata
	Metadata map[string]any
}

type FieldDescriptor struct {
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Visibility  string `json:"visibility,omitempty"`
	Tag         string `json:"tag,omitempty"`
	Description string `json:"description,omitempty"`
}

type FieldInfo struct {
	Name        string `json:"name"`
	Type        string `json:"type"`
	Tag         string `json:"tag,omitempty"`
	Description string `json:"description"`
}

type FunctionDescriptor struct {
	Language    string         `json:"language"`
	Kind        string         `json:"kind"` // function | method | scope | accessor | mutator | constructor
	Name        string         `json:"name"`
	Namespace   string         `json:"namespace,omitempty"`
	Receiver    string         `json:"receiver,omitempty"` // Parent type for methods
	Signature   string         `json:"signature,omitempty"`
	Description string         `json:"description,omitempty"`
	Location    SymbolLocation `json:"location,omitempty"`

	Parameters []ParamDescriptor  `json:"parameters,omitempty"`
	Returns    []ReturnDescriptor `json:"returns,omitempty"`

	Visibility string `json:"visibility,omitempty"` // public | protected | private | exported (Go)
	IsStatic   bool   `json:"is_static,omitempty"`
	IsAbstract bool   `json:"is_abstract,omitempty"`
	IsFinal    bool   `json:"is_final,omitempty"`

	Code     string         `json:"code,omitempty"`
	Tags     []string       `json:"tags,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type MethodInfo struct {
	Name         string       `json:"name"`
	Signature    string       `json:"signature"`
	Description  string       `json:"description"`
	Parameters   []ParamInfo  `json:"parameters"`
	Returns      []ReturnInfo `json:"returns"`
	ReceiverType string       `json:"receiver_type,omitempty"`
	IsExported   bool         `json:"is_exported"`
	FilePath     string       `json:"file_path,omitempty"`
	StartLine    int          `json:"start_line,omitempty"`
	EndLine      int          `json:"end_line,omitempty"`
	Code         string       `json:"code,omitempty"`
}

type ParamDescriptor struct {
	Name        string `json:"name"`
	Type        string `json:"type,omitempty"`
	Description string `json:"description,omitempty"`
}

type ParamInfo struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

type PathAnalyzer interface {
	AnalyzePaths(paths []string) ([]CodeChunk, error)
}

type RelationDescriptor struct {
	Name          string `json:"name"`
	RelationKind  string `json:"relation_kind"`            // hasOne, hasMany, belongsTo, implements, embeds, etc.
	RelatedSymbol string `json:"related_symbol,omitempty"` // Fully-qualified related symbol (e.g., App\\Organ)
	ForeignKey    string `json:"foreign_key,omitempty"`
	LocalKey      string `json:"local_key,omitempty"`
	Description   string `json:"description,omitempty"`
}

type ReturnDescriptor struct {
	Type        string `json:"type,omitempty"`
	Description string `json:"description,omitempty"`
	SourceHint  string `json:"source_hint,omitempty"` // phpdoc | type_hint | inferred | unknown
}

type ReturnInfo struct {
	Type        string `json:"type"`
	Description string `json:"description"`
}

type SymbolDescriptor struct {
	Language  string `json:"language"`
	Kind      string `json:"kind"` // class | interface | trait | function | method | constant | enum | file
	Name      string `json:"name"`
	Namespace string `json:"namespace,omitempty"`
	Package   string `json:"package,omitempty"`

	Signature   string         `json:"signature,omitempty"`
	Description string         `json:"description,omitempty"`
	Location    SymbolLocation `json:"location,omitempty"`

	Tags     []string       `json:"tags,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type SymbolLocation struct {
	FilePath  string `json:"file_path,omitempty"`
	URI       string `json:"uri,omitempty"`
	StartLine int    `json:"start_line,omitempty"`
	EndLine   int    `json:"end_line,omitempty"`
}