// Package godocs provides parsing and extraction for Go package documentation
// from pkg.go.dev and similar documentation sites.
package godocs

import "time"

// Package represents a Go package's documentation.
type Package struct {
	// Import path (e.g., "github.com/user/repo/pkg")
	ImportPath string `json:"import_path"`

	// Package name (last element of import path)
	Name string `json:"name"`

	// Synopsis is a short one-line description
	Synopsis string `json:"synopsis"`

	// Full documentation text
	Doc string `json:"doc"`

	// Version information
	Version string `json:"version"`

	// Module information
	Module *Module `json:"module,omitempty"`

	// License information
	Licenses []License `json:"licenses,omitempty"`

	// Functions exported by the package
	Functions []*Function `json:"functions,omitempty"`

	// Types defined in the package
	Types []*Type `json:"types,omitempty"`

	// Constants defined in the package
	Constants []*Value `json:"constants,omitempty"`

	// Variables defined in the package
	Variables []*Value `json:"variables,omitempty"`

	// Examples for the package
	Examples []*Example `json:"examples,omitempty"`

	// Import count
	ImportedBy int `json:"imported_by"`

	// Repository URL
	Repository string `json:"repository,omitempty"`

	// Documentation URL
	DocURL string `json:"doc_url"`

	// When the documentation was fetched
	FetchedAt time.Time `json:"fetched_at"`
}

// Module represents Go module information.
type Module struct {
	Path    string `json:"path"`
	Version string `json:"version"`
}

// License represents license information.
type License struct {
	Name string `json:"name"`
	Path string `json:"path,omitempty"`
}

// Function represents a function declaration.
type Function struct {
	Name      string     `json:"name"`
	Doc       string     `json:"doc,omitempty"`
	Signature string     `json:"signature"`
	Examples  []*Example `json:"examples,omitempty"`
}

// Type represents a type declaration.
type Type struct {
	Name       string     `json:"name"`
	Doc        string     `json:"doc,omitempty"`
	Kind       TypeKind   `json:"kind"`
	Underlying string     `json:"underlying,omitempty"` // For type aliases
	Fields     []*Field   `json:"fields,omitempty"`     // For structs
	Methods    []*Method  `json:"methods,omitempty"`
	Examples   []*Example `json:"examples,omitempty"`
}

// TypeKind represents the kind of type.
type TypeKind string

const (
	TypeKindBasic     TypeKind = "basic"
	TypeKindStruct    TypeKind = "struct"
	TypeKindInterface TypeKind = "interface"
	TypeKindAlias     TypeKind = "alias"
	TypeKindFunc      TypeKind = "func"
)

// Field represents a struct field.
type Field struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Doc      string `json:"doc,omitempty"`
	Tag      string `json:"tag,omitempty"`
	Embedded bool   `json:"embedded,omitempty"`
	Exported bool   `json:"exported"`
}

// Method represents a method on a type.
type Method struct {
	Name      string `json:"name"`
	Doc       string `json:"doc,omitempty"`
	Signature string `json:"signature"`
	Receiver  string `json:"receiver,omitempty"`
}

// Value represents a constant or variable declaration.
type Value struct {
	Name    string   `json:"name"`
	Doc     string   `json:"doc,omitempty"`
	Type    string   `json:"type,omitempty"`
	Value   string   `json:"value,omitempty"`
	Names   []string `json:"names,omitempty"` // For const groups
	IsConst bool     `json:"is_const"`
}

// Example represents a code example.
type Example struct {
	Name    string `json:"name"`
	Doc     string `json:"doc,omitempty"`
	Code    string `json:"code"`
	Output  string `json:"output,omitempty"`
	PlayURL string `json:"play_url,omitempty"`
}

// SearchResult represents a search result from pkg.go.dev.
type SearchResult struct {
	Name       string `json:"name"`
	Path       string `json:"path"`
	Synopsis   string `json:"synopsis"`
	ImportedBy int    `json:"imported_by"`
	Version    string `json:"version"`
	Published  string `json:"published"`
	License    string `json:"license"`
	URL        string `json:"url"`
}

// Symbol represents a symbol (function, type, etc.) within a package.
type Symbol struct {
	Name      string `json:"name"`
	Kind      string `json:"kind"` // function, type, constant, variable
	Signature string `json:"signature,omitempty"`
	Doc       string `json:"doc,omitempty"`
	Recv      string `json:"recv,omitempty"` // For methods
}
