source

type DocSnippet struct {
	// EntityName is the name of the PHP class or function (e.g., "WP_Query").
	EntityName string `json:"entity_name"`

	// MethodName is the name of the method within the entity, if this snippet
	// is method-level. Empty for class-level snippets.
	MethodName string `json:"method_name,omitempty"`

	// Signature is the full PHP method signature including parameters and return
	// type, if available.
	Signature string `json:"signature,omitempty"`

	// Description is the PHPDoc summary for this entity or method.
	Description string `json:"description"`

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

	// ReturnType is the PHP type of the method's return value.
	ReturnType string `json:"return_type,omitempty"`

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

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

	// WrappedSource is the source code of the underlying function that this
	// method delegates to, when wrapper detection resolves a chain.
	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 documentation URL for this snippet.
	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 (e.g., @uses, @see).
	Relations []Relation `json:"relations,omitempty"`
}

type Entity struct {
	Slug        string
	Name        string
	Kind        string // "class", "interface", "trait", "function"
	Description string
	SourceFile  string
	SourceCode  string
	URL         string
	Properties  []Property
}

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

type LibraryMeta struct {
	Name        string
	Description string
	SourceURL   string
	Version     string
	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
	Relations     []Relation
}

type Parameter struct {
	// Name is the PHP parameter name including the leading dollar sign (e.g., "$post_id").
	Name string `json:"name"`

	// Type is the PHP type annotation (e.g., "int", "WP_Post|null").
	Type string `json:"type"`

	// Required is true when the parameter has no default value and is not
	// described as optional in the PHPDoc.
	Required bool `json:"required"`

	// Description is the PHPDoc 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, either "uses" (this method calls the target)
	// or "used_by" (this method is called by the target).
	Kind string `json:"kind"`

	// TargetName is the PHP name of the related class or method.
	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 PHPDoc text associated with the relation.
	Description string `json:"description,omitempty"`
}

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

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

	// DiscoverEntities returns URLs of all top-level entities to crawl.
	// The fetch function is provided by the crawler and is rate-limited.
	// DiscoverEntities must be called before DetectWrapper, ResolveWrapperURL,
	// or ParseSourceCode; those methods depend on the internal index built here.
	DiscoverEntities(ctx context.Context, fetch FetchFunc) ([]string, error)

	// ParseEntity parses a single entity page and returns its data
	// plus a list of method URLs to crawl next.
	ParseEntity(ctx context.Context, url string, body []byte) (*Entity, []string, error)

	// ParseMethod parses a single method/function detail page.
	ParseMethod(ctx context.Context, url string, body []byte) (*Method, error)

	// DetectWrapper analyzes a method's source code and returns wrapper info.
	// Returns (isWrapper, targetName, targetKind) where targetKind is
	// "function", "self_method", or "static_method".
	// Returns (false, "", "") if the method is not a wrapper, or if
	// DiscoverEntities has not yet been called.
	DetectWrapper(method *Method) (bool, string, string)

	// ResolveWrapperURL constructs the URL to fetch the wrapped method's page.
	// Returns an empty string if the target cannot be resolved or if
	// DiscoverEntities has not yet been called.
	ResolveWrapperURL(targetName, targetKind, entitySlug string) string

	// ParseSourceCode extracts just the source code from a page body.
	// Called during wrapper chain resolution to obtain the source of a
	// delegated-to function or method.
	ParseSourceCode(url string, body []byte) (string, error)
}