collector

type ApiBody ¶

type ApiBody = model.ApiBody

type ApiEndpoint ¶

type ApiEndpoint = model.ApiEndpoint

Re-export model types so existing collector implementations need no import changes.

func UnmarshalEndpoints(data []byte) ([]ApiEndpoint, error)

type ApiHeader ¶

type ApiHeader = model.ApiHeader

type ApiParameter ¶

type ApiParameter = model.ApiParameter

type CollectContext ¶

type CollectContext struct {
	// SourceDir is the absolute path to the root of the source tree to parse.
	SourceDir string `json:"sourceDir"`

	// SourceFile is the absolute path to a specific source file when file-level
	// export is requested. When empty, all files under SourceDir are scanned.
	// Collectors may use this to optimize parsing (e.g. only parse one file)
	// or ignore it and rely on post-collection filtering by the engine.
	SourceFile string `json:"sourceFile,omitempty"`

	// Frameworks is an optional list of framework hints (e.g. ["spring-mvc", "feign"]).
	Frameworks []string `json:"frameworks,omitempty"`

	// NoDeps disables dependency-based type resolution for this collection.
	// Collectors skip external tooling and dependency artifacts entirely and
	// report DependencyResolutionDisabled.
	NoDeps bool `json:"noDeps,omitempty"`

	// Config holds collector-specific key-value configuration.
	Config map[string]string `json:"config,omitempty"`
}

CollectContext carries the inputs needed by a Collector to perform collection.

type Collector ¶

type Collector interface {
	// Name returns the unique identifier for this collector (e.g. "java", "go").
	Name() string

	// SupportedLanguages returns the list of language identifiers this collector handles.
	SupportedLanguages() []string

	// Collect parses the source directory described by ctx and returns the discovered endpoints.
	Collect(ctx CollectContext) ([]ApiEndpoint, error)
}

Collector is the interface every language/framework collector must implement.

type Dependency ¶

type Dependency struct {
	Name    string
	Version string
}

type DependencyResolution ¶

type DependencyResolution struct {
	// State classifies the outcome.
	State DependencyResolutionState

	// Detail explains a non-active state: it names the missing tool or
	// artifacts with guidance for restoring them. Empty for Active, which
	// needs no explanation.
	Detail string

	// ResolvedTypes counts the distinct endpoint types expanded from
	// dependencies during the last Collect call. Meaningful only for Active;
	// zero there means the endpoints never referenced a dependency type.
	ResolvedTypes int
}

DependencyResolution reports how dependency-based type resolution fared during the last Collect call.

Dependency types live outside the project's own sources — dependency JARs, node_modules, site-packages, the Go module cache — and reaching them depends on tooling or artifacts that are often absent. When resolution is skipped silently, an export full of opaque scalar types looks like a resolution success; this report tells the two apart.

type DependencyResolutionReporter ¶

type DependencyResolutionReporter interface {
	// DependencyResolution reports the outcome of dependency-based type
	// resolution during the last Collect call.
	DependencyResolution() DependencyResolution
}

DependencyResolutionReporter is an optional interface implemented by collectors whose type resolution can reach beyond the project's own sources.

Like UnresolvedReporter, it is deliberately not part of Collector: subprocess plugins cannot report across the process boundary, so the engine must type-assert.

type DependencyResolutionState ¶

type DependencyResolutionState string

DependencyResolutionState classifies the outcome of dependency-based type resolution during a Collect call.

const (
	// DependencyResolutionActive means the dependency resolver ran and could
	// expand types beyond the project's own sources.
	DependencyResolutionActive DependencyResolutionState = "active"

	// DependencyResolutionToolMissing means resolution was skipped because a
	// prerequisite is absent: an external tool is not on PATH, or the artifacts
	// a resolver reads from have not been fetched. Detail names it and says
	// how to restore the capability.
	DependencyResolutionToolMissing DependencyResolutionState = "tool-missing"

	// DependencyResolutionNoDeps means there was nothing to resolve: the
	// project carries no dependency manifest or declares no dependencies.
	DependencyResolutionNoDeps DependencyResolutionState = "no-deps"

	// DependencyResolutionDisabled means the caller turned dependency
	// resolution off (e.g. the --no-deps flag).
	DependencyResolutionDisabled DependencyResolutionState = "disabled"
)

type DependencyResolver ¶

type DependencyResolver interface {
	DetectDependencies(sourceDir string) ([]Dependency, error)

	ResolveType(typeName string) *ResolvedType
}

type FrameworkReporter ¶

type FrameworkReporter interface {
	// Frameworks returns the frameworks the last Collect call matched, in the
	// order the collector declares them. Empty when the collector cannot tell
	// or matched none.
	Frameworks() []string
}

FrameworkReporter is an optional interface implemented by collectors that scan several frameworks and know which ones actually produced endpoints.

A collector is named after a language ("java"), so the name alone does not say which framework a document was read from. Reporting the frameworks lets an export name its source instead of leaving the reader to guess (#170).

Like UnresolvedReporter it is deliberately not part of Collector: subprocess plugins cannot report across the process boundary, so the engine must type-assert.

type ResolvedField ¶

type ResolvedField struct {
	Name     string
	Type     string
	Required bool
}

type ResolvedType ¶

type ResolvedType struct {
	Name               string
	Fields             []ResolvedField
	TypeParameters     []string
	SuperClass         string
	SuperClassTypeArgs []string
	IsInterface        bool
	Interfaces         []string
}

type UnresolvedReporter ¶

type UnresolvedReporter interface {
	// Unresolved returns the unresolved type names mapped to how many times
	// each one was encountered during the last Collect call.
	Unresolved() map[string]int
}

UnresolvedReporter is an optional interface implemented by collectors whose type resolvers can report type names they failed to expand.

A resolver that cannot resolve a type falls back to an opaque single-value model, which is structurally identical to a resolved primitive. Collectors implementing this interface let callers (e.g. the engine) tell the two apart and surface a diagnostic instead of silently dropping fields.

It is intentionally not part of Collector: subprocess plugins cannot report across the process boundary, so the engine must type-assert.

type UnresolvedSet ¶

type UnresolvedSet struct {
	// contains filtered or unexported fields
}

UnresolvedSet accumulates unresolved type names across concurrent parsers. A nil *UnresolvedSet is usable: Record is a no-op and Counts returns nil, so parsers can accept it as an optional parameter.

func NewUnresolvedSet() *UnresolvedSet

func (s *UnresolvedSet) Counts() map[string]int

func (s *UnresolvedSet) Record(typeName string)

type WarningsReporter ¶

type WarningsReporter interface {
	// Warnings returns the diagnostics raised during the last Collect call,
	// one message per gap. Each message should name the endpoint it concerns.
	Warnings() []string
}

WarningsReporter is an optional interface implemented by collectors that can finish a collection while knowing part of the export is thinner than the source. A response body the collector had to leave opaque is the example this was added for: the document is produced, but a whole section is marked rather than resolved.

Without it the only evidence is the document itself, and an opaque section looks like an API that returns nothing.

Like UnresolvedReporter and DependencyResolutionReporter it is deliberately not part of Collector: subprocess plugins cannot report across the process boundary, so the engine must type-assert.