scanner

type ConstantInfo struct {
	Name       string
	FilePath   string // Added: Absolute path to the file where this const is defined
	Doc        string
	Type       *FieldType // Changed from string to *FieldType
	Value      string
	RawValue   string   // The raw, unquoted string value, if the constant is a string.
	IsExported bool     // Added to indicate if the constant is exported
	Node       ast.Node // Added: AST node for position, if needed, though FilePath is primary
	ConstVal   constant.Value
	IotaValue  int // The value of iota for the spec this constant was in.
	ValExpr    ast.Expr
}

type ExternalTypeOverride map[string]*TypeInfo

type FieldInfo struct {
	Name       string
	Doc        string
	Type       *FieldType
	Tag        string
	Embedded   bool
	IsExported bool // True if the field is exported (starts with an uppercase letter).
}

type FieldType struct {
	Name         string       `json:"name"`
	PkgName      string       `json:"pkgName,omitempty"` // e.g., "json", "models"
	MapKey       *FieldType   `json:"mapKey,omitempty"`  // For map types
	Elem         *FieldType   `json:"elem,omitempty"`    // For slice, map, pointer, array types
	IsPointer    bool         `json:"isPointer,omitempty"`
	IsSlice      bool         `json:"isSlice,omitempty"`
	IsMap        bool         `json:"isMap,omitempty"`
	IsTypeParam  bool         `json:"isTypeParam,omitempty"`  // True if this FieldType refers to a type parameter
	IsConstraint bool         `json:"isConstraint,omitempty"` // True if this FieldType represents a type constraint
	TypeArgs     []*FieldType `json:"typeArgs,omitempty"`     // For instantiated generic types, e.g., T in List[T]

	Definition         *TypeInfo `json:"-"` // Caches the resolved type definition. Avoid cyclic JSON.
	IsResolvedByConfig bool      `json:"isResolvedByConfig,omitempty"`
	IsBuiltin          bool      `json:"isBuiltin,omitempty"`

	// Resolver, FullImportPath, and TypeName are used for on-demand package scanning.
	// They are exported to allow consumers of the library to construct a resolvable
	// FieldType manually, for instance when parsing type information from an
	// annotation rather than from a Go AST node.
	Resolver       PackageResolver `json:"-"` // For lazy-loading the type definition.
	FullImportPath string          `json:"-"` // Full import path of the type, e.g., "example.com/project/models".
	TypeName       string          `json:"-"` // The name of the type within its package, e.g., "User".
	CurrentPkg     *PackageInfo    `json:"-"` // Reference to the package where this type is used.
}

type FunctionInfo struct {
	Name       string           `json:"name"`
	FilePath   string           `json:"filePath"`
	Doc        string           `json:"doc,omitempty"`
	Receiver   *FieldInfo       `json:"receiver,omitempty"`
	TypeParams []*TypeParamInfo `json:"typeParams,omitempty"` // For generic functions
	Parameters []*FieldInfo     `json:"parameters,omitempty"`
	Results    []*FieldInfo     `json:"results,omitempty"`
	IsVariadic bool             `json:"isVariadic,omitempty"`
	AstDecl    *ast.FuncDecl    `json:"-"` // Avoid cyclic JSON.
}

type InterfaceInfo struct {
	Methods []*MethodInfo
}

type Kind int

type MethodInfo struct {
	Name       string
	Parameters []*FieldInfo
	Results    []*FieldInfo
}

type Overlay map[string][]byte

type PackageImports struct {
	Name        string
	ImportPath  string
	Imports     []string
	FileImports map[string][]string // file path -> import paths
}

type PackageInfo struct {
	Name       string
	Path       string
	ImportPath string // Added: Canonical import path of the package
	ModulePath string // The go module path this package belongs to.
	ModuleDir  string // The absolute path to the module's root directory
	Files      []string
	Types      []*TypeInfo
	Constants  []*ConstantInfo
	Variables  []*VariableInfo
	Functions  []*FunctionInfo
	Fset       *token.FileSet       // Added: Fileset for position information
	AstFiles   map[string]*ast.File // Added: Parsed AST for each file
	// contains filtered or unexported fields
}

type PackageResolver interface {
	ScanPackageByImport(ctx context.Context, importPath string) (*PackageInfo, error)
}

type Scanner struct {
	ExternalTypeOverrides ExternalTypeOverride
	Overlay               Overlay
	// contains filtered or unexported fields
}

type StructInfo struct {
	Fields []*FieldInfo
}

type TypeInfo struct {
	Name       string           `json:"name"`
	PkgPath    string           `json:"pkgPath"`
	FilePath   string           `json:"filePath"`
	Doc        string           `json:"doc,omitempty"`
	Kind       Kind             `json:"kind"`
	TypeParams []*TypeParamInfo `json:"typeParams,omitempty"` // For generic types
	Node       ast.Node         `json:"-"`                    // Avoid cyclic JSON with Node itself.
	Struct     *StructInfo      `json:"struct,omitempty"`
	Func       *FunctionInfo    `json:"func,omitempty"` // For type alias to func type
	Interface  *InterfaceInfo   `json:"interface,omitempty"`
	Underlying *FieldType       `json:"underlying,omitempty"` // For alias types

	// --- Fields for Enum-like patterns ---
	IsEnum      bool            `json:"isEnum,omitempty"`      // True if this type is identified as an enum
	EnumMembers []*ConstantInfo `json:"enumMembers,omitempty"` // List of constants belonging to this enum type

	// --- Fields for inspect mode ---
	Inspect           bool            `json:"-"` // Flag to enable inspection logging
	Logger            *slog.Logger    `json:"-"` // Logger for inspection
	Fset              *token.FileSet  `json:"-"` // Fileset for position information
	ResolutionContext context.Context `json:"-"` // Context for resolving nested types
}

type TypeParamInfo struct {
	Name       string     `json:"name"`
	Constraint *FieldType `json:"constraint,omitempty"`
}

type VariableInfo struct {
	Name       string
	FilePath   string
	Doc        string
	Type       *FieldType
	IsExported bool
	Node       ast.Node
}

type Visitor interface {
	// Visit is called for each package discovered during the walk.
	// It can inspect the package's imports and return the list of
	// imports that the walker should follow next. Returning an empty
	// slice stops the traversal from that node.
	Visit(pkg *PackageImports) (importsToFollow []string, err error)
}