Documentation
¶
Overview ¶
Package wpgithub — ast.go: tree-sitter PHP AST walker and wrapper detector. This file is intentionally separate from phpdoc.go (regex-based PHPDoc parser) because the two parsers have different inputs ([]byte vs string), different dependencies (go-tree-sitter vs regexp), and different reasons to change.
Package wpgithub — parser.go: byte-scan bridge between the PHPDoc regex parser (phpdoc.go) and the tree-sitter AST walker (ast.go).
findPrecedingDoc is a bridge utility: it locates the raw /** ... */ block that immediately precedes a declaration, so that the PHPDoc parser can process it. It belongs to neither parser exclusively.
Package wpgithub — phpdoc.go: regex-based PHPDoc comment parser. This file is intentionally separate from ast.go (tree-sitter AST walker) because the two parsers have different inputs (string vs []byte), different dependencies (regexp vs go-tree-sitter), and different reasons to change.
Package wpgithub provides a documentation source adapter that reads WordPress PHP source code from a local clone of the WordPress/WordPress GitHub repository. It parses raw PHP source via tree-sitter to extract classes, functions, methods, properties, and PHPDoc without making any network calls during parsing.
Index ¶
- Constants
- Variables
- func EnsureRepo(ctx context.Context, opts DownloadOptions) (repoPath, version string, err error)
- type DownloadOptions
- type Option
- type WPGithubSource
- func (s *WPGithubSource) DetectWrapper(method *source.Method) (bool, string, string)
- func (s *WPGithubSource) DiscoverEntities(ctx context.Context, fetch source.FetchFunc) ([]string, error)
- func (s *WPGithubSource) ID() string
- func (s *WPGithubSource) Meta() source.LibraryMeta
- func (s *WPGithubSource) ParseEntity(ctx context.Context, url string, body []byte) (*source.Entity, []string, error)
- func (s *WPGithubSource) ParseMethod(ctx context.Context, url string, body []byte) (*source.Method, error)
- func (s *WPGithubSource) ParseSourceCode(url string, body []byte) (string, error)
- func (s *WPGithubSource) ResolveWrapperURL(targetName, targetKind, entitySlug string) string
Constants ¶
const ( MethodAuto = "auto" // try tarball, fall back to git clone MethodTarball = "tarball" // HTTP tarball only (codeload.github.com) MethodGit = "git" // git clone --depth 1 over github.com )
Acquisition methods for DownloadOptions.Method.
Variables ¶
var ( // ErrVersionNotFound indicates the requested WordPress version has no // corresponding tag/tarball upstream. ErrVersionNotFound = errors.New("wordpress version not found upstream") // ErrRateLimited indicates the GitHub API rejected a request because the // rate limit was exhausted. ErrRateLimited = errors.New("github api rate limited") // ErrUnsafeArchive indicates a tar entry that would escape the extraction // root or is of an unsupported (non-file/dir) type. ErrUnsafeArchive = errors.New("unsafe archive entry") // ErrUnexpectedArchiveLayout indicates the archive did not contain the // expected single top-level directory / WordPress source layout. ErrUnexpectedArchiveLayout = errors.New("unexpected archive layout") // ErrArchiveTooLarge indicates the archive exceeded the extracted-size or // entry-count caps (decompression-bomb defense). ErrArchiveTooLarge = errors.New("archive too large") )
Errors returned by EnsureRepo. Callers can classify them with errors.Is.
Functions ¶
func EnsureRepo ¶
func EnsureRepo(ctx context.Context, opts DownloadOptions) (repoPath, version string, err error)
EnsureRepo resolves the requested WordPress version (or the latest release when Version is empty), ensures an extracted copy exists in the cache, and returns the local repository root plus the resolved literal tag. The returned root directly contains wp-includes/ and wp-admin/includes/, as the parser expects, and the tag is suitable for pinning source links via WithRef.
Types ¶
type DownloadOptions ¶
type DownloadOptions struct {
Version string // empty => resolve latest release
CacheDir string // where versioned extractions are cached
Refresh bool // force re-download even if cached
Method string // MethodAuto (default), MethodTarball, or MethodGit
Token string // optional GitHub API token (GITHUB_TOKEN/GH_TOKEN)
UserAgent string
MaxRetries int // per-request retries on transient failures; <=0 => 3
MaxExtractedB int64 // override for the extracted-size cap; <=0 => default
APIBaseURL string // default https://api.github.com
TarballBaseURL string // default https://github.com (redirects to codeload)
GitRepoURL string // default https://github.com/WordPress/WordPress.git
}
DownloadOptions configures EnsureRepo. The base-URL fields are injectable so tests can point at an httptest.Server; they default to the real endpoints.
type Option ¶
type Option func(*WPGithubSource)
Option customises a WPGithubSource at construction time.
type WPGithubSource ¶
type WPGithubSource struct {
// contains filtered or unexported fields
}
WPGithubSource is a documentation source adapter that reads WordPress PHP source code from a local clone of the WordPress/WordPress GitHub repository. Unlike the HTML-scraping wordpress adapter, this one parses raw PHP source, which allows direct access to source code, PHPDoc, and wrapper detection without making any network calls during parsing.
func New ¶
func New(repoPath string, opts ...Option) *WPGithubSource
New constructs a new WPGithubSource pointing at a local clone of the WordPress/WordPress repository. The index is initialised to an empty (non-nil) state so that DetectWrapper and ResolveWrapperURL are safe to call before DiscoverEntities has been run.
func (*WPGithubSource) DetectWrapper ¶
DetectWrapper analyzes a method's source code for wrapper patterns. It is safe to call before DiscoverEntities — it will return (false,"","") when the index has no data (i.e. no builtins have been detected yet).
func (*WPGithubSource) DiscoverEntities ¶
func (s *WPGithubSource) DiscoverEntities(ctx context.Context, fetch source.FetchFunc) ([]string, error)
DiscoverEntities walks the local repository and returns a sorted list of entity identifiers. The fetch parameter is unused — all discovery reads files locally.
func (*WPGithubSource) ID ¶
func (s *WPGithubSource) ID() string
ID returns the canonical library ID.
func (*WPGithubSource) Meta ¶
func (s *WPGithubSource) Meta() source.LibraryMeta
Meta returns metadata for the library record.
func (*WPGithubSource) ParseEntity ¶
func (s *WPGithubSource) ParseEntity(ctx context.Context, url string, body []byte) (*source.Entity, []string, error)
ParseEntity dispatches to either function-entity or class-entity parsing based on whether the URL contains a fragment.
func (*WPGithubSource) ParseMethod ¶
func (s *WPGithubSource) ParseMethod(ctx context.Context, url string, body []byte) (*source.Method, error)
ParseMethod parses a class method given a URL fragment of the form `path/to/file.php#ClassName::methodName`.
func (*WPGithubSource) ParseSourceCode ¶
func (s *WPGithubSource) ParseSourceCode(url string, body []byte) (string, error)
ParseSourceCode extracts the source code for a specific function or method from a PHP file, identified by the URL fragment.
func (*WPGithubSource) ResolveWrapperURL ¶
func (s *WPGithubSource) ResolveWrapperURL(targetName, targetKind, entitySlug string) string
ResolveWrapperURL constructs a URL identifier for a wrapped target so the crawler can fetch its source. Returns an empty string when no file in the index hosts the requested target. It is safe to call before DiscoverEntities — an empty index simply finds no matches.
Source Files