source

type DocSnippet struct {
	// EntityName is the name of the entity (e.g., "WP_Query", "http.Server").
	EntityName string `json:"entity_name"`

	// MethodName is the name of the method, empty for entity-level snippets.
	MethodName string `json:"method_name,omitempty"`

	// Signature is the full method/function signature.
	Signature string `json:"signature,omitempty"`

	// Description is the documentation summary.
	Description string `json:"description"`

	// Parameters lists the documented parameters.
	Parameters []Parameter `json:"parameters,omitempty"`

	// ReturnType is the return type annotation.
	ReturnType string `json:"return_type,omitempty"`

	// ReturnDesc is the description of the return value.
	ReturnDesc string `json:"return_desc,omitempty"`

	// SourceCode is the source of the entity or method body.
	SourceCode string `json:"source_code"`

	// WrappedSource is the source code of the underlying delegated-to function.
	WrappedSource string `json:"wrapped_source,omitempty"`

	// WrappedMethod is the name of the underlying delegated-to method.
	WrappedMethod string `json:"wrapped_method,omitempty"`

	// URL is the canonical source/documentation URL.
	URL string `json:"url"`

	// Relevance is the BM25 rank score. Lower (more negative) values indicate
	// higher relevance.
	Relevance float64 `json:"relevance"`

	// Relations lists cross-references to related methods.
	Relations []Relation `json:"relations,omitempty"`
}

type Entity struct {
	Slug        string
	Name        string
	Kind        string // Use KindClass, KindFunction, etc.
	Description string
	SourceFile  string
	SourceCode  string
	URL         string
	Visibility  string // "public", "protected", "private", "internal", "package"; empty defaults to "public"
	Deprecated  bool
	Properties  []Property
}

type FetchFunc func(ctx context.Context, id string) ([]byte, error)

type LibraryMeta struct {
	Name        string
	Description string
	SourceURL   string
	Version     string
	Language    string // "php", "go", "python", "javascript", "typescript", "java", "c", "cpp", "csharp", "ruby", "rust"
	TrustScore  float64
}

type Method struct {
	Slug          string
	Name          string
	Signature     string
	Description   string
	Parameters    []Parameter
	ReturnType    string
	ReturnDesc    string
	SourceCode    string
	WrappedSource string
	WrappedMethod string
	URL           string
	Since         string
	Deprecated    bool
	Relations     []Relation
}

type Parameter struct {
	// Name is the parameter name (e.g., "$post_id" in PHP, "ctx" in Go).
	Name string `json:"name"`

	// Type is the type annotation as it appears in source
	// (e.g., "int", "WP_Post|null", "Vec<u8>", "List[int]").
	Type string `json:"type"`

	// Required is true when the parameter has no default value.
	Required bool `json:"required"`

	// Description is the doc comment text for this parameter.
	Description string `json:"description"`
}

type Property struct {
	Name        string
	Type        string
	Description string
	Visibility  string
	Since       string
}

type Relation struct {
	// Kind is the relationship type (e.g., "uses", "used_by", "calls",
	// "implements", "extends", "overrides").
	Kind string `json:"kind"`

	// TargetName is the qualified name of the related entity
	// (e.g., "WP_Query::get_posts()", "net/http.Server").
	TargetName string `json:"target_name"`

	// TargetURL is the canonical documentation URL of the related entity,
	// if available.
	TargetURL string `json:"target_url,omitempty"`

	// Description is any additional text associated with the relation.
	Description string `json:"description,omitempty"`
}

type Source interface {
	// ID returns the canonical library ID (e.g., "/wordpress", "go/stdlib").
	ID() string

	// Meta returns metadata for the library record.
	Meta() LibraryMeta

	// DiscoverEntities returns identifiers for all top-level entities to crawl.
	// Each identifier is an absolute file path optionally suffixed with a fragment
	// (#EntityName) that uniquely identifies one entity in a multi-entity file.
	// The fetch function is provided by the crawler for sources that need to
	// read remote resources during discovery (most local sources ignore it).
	DiscoverEntities(ctx context.Context, fetch FetchFunc) ([]string, error)

	// ParseEntity parses a single entity from file content, identified by entityID.
	// Returns the entity data plus a list of method identifiers to crawl next.
	// For multi-entity files, the implementation uses the fragment in entityID to
	// locate the specific entity within the content bytes.
	ParseEntity(ctx context.Context, entityID string, content []byte) (*Entity, []string, error)

	// ParseMethod parses a single method/function from file content.
	// The methodID contains a fragment identifying the specific method.
	ParseMethod(ctx context.Context, methodID string, content []byte) (*Method, error)

	// DetectWrapper analyzes a method's source code and returns wrapper info.
	// Returns (isWrapper, targetName, targetKind) where targetKind is a
	// language-specific delegation category (e.g., "function", "self_method",
	// "static_method" for PHP; "method", "function" for Go).
	// Returns (false, "", "") if the method is not a wrapper.
	DetectWrapper(method *Method) (bool, string, string)

	// ResolveWrapperURL constructs the identifier to fetch the wrapped target's
	// source. Returns an empty string if the target cannot be resolved.
	ResolveWrapperURL(targetName, targetKind, entitySlug string) string

	// ParseSourceCode extracts just the source code of a specific entity or
	// method from file content, using the fragment in the identifier.
	ParseSourceCode(entityID string, content []byte) (string, error)
}