analyzer

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
}

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 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

	// 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 ---
	// The queue of analysis tasks.
	Worklist []WorklistItem
	// A map to link expressions (like call results) to the tracked value they produce.
	ExprResults map[ast.Expr]*TrackedValue
	// A map to link variable/parameter objects to the tracked value they hold.
	VarValues map[types.Object]*TrackedValue

	// 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

	// OperationMetadata stores metadata parsed from `respec.Route` builders,
	// keyed by the handler's unique types.Object.
	OperationMetadata map[types.Object]*respec.HandlerMetadata
	// 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
}

type WorklistItem struct {
	// The AST node representing the usage of a tracked value (e.g., an `*ast.Ident` for a variable).
	Node ast.Node
	// The value being tracked at this node.
	Value *TrackedValue
}