model

type AssertionPackage struct {
	Tool             string
	Header           string
	Package          string
	DocString        string
	Copyright        string
	Receiver         string
	Imports          ImportMap
	EnableFormat     bool
	EnableForward    bool
	EnableGenerics   bool
	EnableExamples   bool
	RunnableExamples bool

	Functions Functions
	Types     []Ident
	Consts    []Ident
	Vars      []Ident

	// extraneous information when scanning in collectDoc mode
	ExtraComments []ExtraComment
	Context       *Document

	// Overridable context for test generation
	TestDataPath string
	TestPackage  bool
}

type CommentTag uint8

type Document struct {
	Title         string
	Domain        string
	Description   string
	Path          string // document folder, relative to its parent if any
	File          string // document name, e.g. _index.md, string.md
	GitHubURL     string
	PkgGoDevURL   string
	Kind          KindDoc           // page or index or folder
	Documents     []Document        // for folders, their content [Document]
	Index         []IndexEntry      // for indexes, their entry list
	Package       *AssertionPackage // subset of the package that pertains to this document
	ExtraPackages ExtraPackages
	RefCount      int
	Weight        int
}

type Documentation struct {
	Package   *AssertionPackage // the complete source package being documented
	Documents []Document        // Documents is a collection of markdown pages or folders
}

type ExtraComment struct {
	Tag  CommentTag
	Key  string
	Text string
}

type ExtraPackages []*AssertionPackage

type Function struct {
	TestData

	ID            string
	Name          string
	SourcePackage string
	TargetPackage string
	DocString     string
	UseMock       string
	Params        Parameters
	AllParams     Parameters
	Returns       Parameters
	TypeParams    []TypeParam
	IsGeneric     bool
	IsHelper      bool
	IsDeprecated  bool
	IsConstructor bool
	Tests         []Test
	// extraneous information when scanning in collectDoc mode
	Domain        string
	SourceLink    *token.Position
	ExtraComments []ExtraComment
	Examples      []Renderable // testable examples as a collection of [Renderable] examples
	Context       *Document
}

type FunctionWithContext struct {
	Function

	Package        string
	Receiver       string
	EnableFormat   bool
	EnableForward  bool
	EnableGenerics bool
	EnableExamples bool
}

type Functions []Function

type Ident struct {
	ID            string
	Name          string
	SourcePackage string
	TargetPackage string
	DocString     string
	IsAlias       bool
	IsDeprecated  bool
	Function      *Function // for function types (or vars)

	// extraneous information when scanning in collectDoc mode
	Domain        string
	SourceLink    *token.Position
	ExtraComments []ExtraComment
	Examples      []Renderable // testable examples as a collection of [Renderable] examples
}

type ImportMap map[string]string

type IndexEntry struct {
	Name        string
	Title       string
	Description string
	Link        string
	RefCount    int
	Weight      int
}

type KindDoc uint8

type Parameter struct {
	Name       string
	GoType     string
	Selector   string
	IsVariadic bool
	IsGeneric  bool
}

type Parameters []Parameter

type Renderable interface {
	Render() string
}

type ScopeKind string

type Test struct {
	TestedValues     []TestValue         // Parsed test value expressions
	TestedValue      string              // Original raw string, kept for auditability
	ExpectedOutcome  TestExpectedOutcome // Expected test outcome (success/failure/panic)
	AssertionMessage string              // Optional assertion message for panic tests
	IsFirst          bool
	Pkg              string
}

type TestData struct {
	TestCall         string
	TestMock         string
	TestErrorPrefix  string
	TestMockFailure  string
	TestPanicWrapper string
	TestMsg          string
}

type TestExpectedOutcome uint8

type TestValue struct {
	Raw   string   // Original string from doc comment
	Expr  ast.Expr // Parsed Go expression (nil if parse failed)
	Error error    // Parse error if any
}

type TypeParam struct {
	Name       string // type parameter name (e.g., "B")
	Constraint string // constraint type (e.g., "Boolean", "cmp.Ordered")
}