analyzer

type Diagnostic struct {
	Severity Severity
	Pos      token.Pos
	Message  string
	// Location is the resolved "file:line:col", filled in by Render.
	Location string
}

type ParsedComment struct {
	// Summary is a brief summary of the comment.
	Summary string
	// Description is a longer description of the comment.
	Description string
	// Tags are a list of tags extracted from the comment.
	Tags []string
	// SummaryExplicit reports whether Summary came from an @summary line rather
	// than from the first line of prose. An explicit summary is used verbatim;
	// a derived one is reworded for documentation.
	SummaryExplicit bool
}

type ResolvedType struct {
	// The canonical representation of the type. This is what we use for reliable comparisons.
	Object *types.Named
	// A pointer to the original definition from the config file.
	Definition *config.RouterDefinition
}

type SchemaGenerator struct {

	// The final map of named components that will be added to the spec.
	Components map[string]*openapi3.SchemaRef
	// contains filtered or unexported fields
}

type Severity int

type SpecSite struct {
	// Metadata parsed from the builder chain.
	Metadata *meta.HandlerMetadata
	// HandlerExpr is the argument given to respec.Handler.
	HandlerExpr ast.Expr
	// HandlerObj is the handler's object, when it is a named function. Nil for
	// function literals.
	HandlerObj types.Object
	// HandlerBody is the code to scan for schemas and parameters, from either a
	// declaration or a literal.
	HandlerBody *ast.BlockStmt
	// Name is a human-readable handler name used for summaries and operation IDs.
	Name string
	// Pos anchors diagnostics to the builder chain.
	Pos token.Pos
	// Linked records whether any route resolved to this site. An unlinked site
	// means the user wrote metadata that never reached the spec.
	Linked bool
}

type State struct {
	Fset *token.FileSet

	// A map of fully-qualified type names to their resolved canonical types.
	// This is populated by the resolver (Phase 1).
	// Example key: "github.com/go-chi/chi/v5.Mux"
	ResolvedRouterTypes map[string]*ResolvedType
	// ResolvedRouterNames lists the router types actually found in the project,
	// for reporting.
	ResolvedRouterNames []string

	// The discovered universe of all relevant declarations in the project.
	// This is populated by the universe discoverer (Phase 2).
	Universe *Universe

	// --- Data Flow Analysis State ---
	// A map to link variable/parameter objects to the tracked value they hold.
	VarValues map[types.Object]*TrackedValue

	// Diagnostics collected during analysis. Every place the analyzer gives up
	// on a route records one; silence used to be the only signal that something
	// had been dropped.
	Diagnostics []Diagnostic

	// The root of the final constructed API route graph.
	RouteGraph *model.RouteNode

	// --- Schema Generation State ---
	// The schema generator instance.
	SchemaGen *SchemaGenerator

	Config *config.Config

	GroupMetadata model.GroupMetadataMap

	// SpecSites holds every respec.Handler builder chain found in the source.
	SpecSites []*SpecSite
	// contains filtered or unexported fields
}

type TrackedValue struct {
	// The expression where this value was created (e.g., the `chi.NewRouter()` call).
	Source ast.Expr
	// The specific router definition this value corresponds to.
	RouterDef *config.RouterDefinition

	// --- Chaining and Hierarchy ---
	Parent     *TrackedValue
	PathPrefix string
	// The node in our API graph that corresponds to this specific router or group.
	Node *model.RouteNode
}

type Universe struct {
	// A map of function objects to their AST declaration nodes.
	Functions map[types.Object]*ast.FuncDecl

	// A map of constant objects to their value specifications.
	// This helps in resolving path segments that are defined as constants.
	Constants map[types.Object]*ast.ValueSpec
}