toolchain

Documentation

Overview

Package toolchain inspects and describes pinned external tools. It resolves a tool's executable path, detects its installed version, and reports whether that version matches the profile pin. Capabilities carry the per-tool metadata (version-detection strategy, install strategy, archive spec) consumed by the inspector and installer.

Index

• func ExtractFirstToken(output string) (version string, err error)
• func ExtractGoToken(output string) (version string, err error)
• func ExtractPrefixedLine(output string) (version string, err error)
• func IsInstalled(ctx context.Context, runner CommandRunner, tool Tool, path string) (installed bool, err error)
• type Capability
• type CommandRunner
• type GitHubInstall
• type GoInstall
• type InstallMethod
• type NoInstall
• type NpmInstall
• type Status
  • func InspectTools(ctx context.Context, runner CommandRunner, tools map[string]Tool, ...) (statuses []Status)
• type StatusMap
  • func NewStatusMap(statuses []Status) (m StatusMap)
  • func (m StatusMap) AreAllValid(ids []string) (valid bool)
  • func (m StatusMap) ExplainIssues(ids []string) (message string)
• type Tool
• type VersionMethod
  • func DetectByCommand(argument string, extract func(string) (string, error)) (method VersionMethod)
  • func DetectByGoBinary(modulePath string) (method VersionMethod)

Functions

func ExtractFirstToken

func ExtractFirstToken(output string) (version string, err error)

ExtractFirstToken returns the first whitespace-delimited token, stripped of a leading v.

func ExtractGoToken

func ExtractGoToken(output string) (version string, err error)

ExtractGoToken extracts the goX.Y.Z token from `go version` output.

func ExtractPrefixedLine

func ExtractPrefixedLine(output string) (version string, err error)

ExtractPrefixedLine finds the first "version:" prefixed line and returns its value.

func IsInstalled

func IsInstalled(
	ctx context.Context,
	runner CommandRunner,
	tool Tool,
	path string,
) (installed bool, err error)

IsInstalled reports whether a tool matching the pinned version is already installed at the given path.

Types

type Capability

type Capability struct {
	ID      string
	Name    string
	Command string

	Version VersionMethod
	Install InstallMethod
}

Capability describes an external tool's command and the strategies for detecting its version and installing it.

type CommandRunner

type CommandRunner interface {
	// ResolvePath finds the full path to command, searching the PATH in environment.
	ResolvePath(
		ctx context.Context,
		environment map[string]string,
		command string,
	) (path string, err error)

	// Run executes the binary at path with arguments, using environment, and returns its
	// combined output.
	Run(
		ctx context.Context,
		environment map[string]string,
		path string,
		arguments []string,
	) (output string, err error)
}

CommandRunner resolves and executes commands for tool version inspection.

type GitHubInstall

type GitHubInstall struct {
	Owner      string
	Repository string

	// Tag is a fmt.Sprintf format string that produces the release tag, taking the version.
	Tag string

	// Asset is a fmt.Sprintf format string that produces the archive filename, taking the tag and
	// platform.
	Asset string

	// Path is a fmt.Sprintf format string that produces the executable path inside the archive,
	// taking the tag.
	Path string

	// Platforms maps "os/arch" to the per-platform token substituted into Asset.
	Platforms map[string]string
}

GitHubInstall installs a tool from a GitHub release archive.

type GoInstall

type GoInstall struct {
	Source string
}

GoInstall runs `go install <Source>@<version>`.

type InstallMethod

type InstallMethod interface {
	// contains filtered or unexported methods
}

InstallMethod selects how a missing tool is installed.

type NoInstall

type NoInstall struct{}

NoInstall means the tool is never installed by the engine (assumed present on the host).

type NpmInstall

type NpmInstall struct {
	Source string
}

NpmInstall runs `npm install <Source>@<version>`.

type Status

type Status struct {
	Tool    Tool
	Path    string
	Version string
	Valid   bool
	Issue   string
}

Status represents the outcome of inspecting one tool.

func InspectTools

func InspectTools(
	ctx context.Context,
	runner CommandRunner,
	tools map[string]Tool,
	environment map[string]string,
) (statuses []Status)

InspectTools reports the status of each tool in tools, sorted by tool ID.

type StatusMap

type StatusMap map[string]Status

StatusMap is a tool-status lookup keyed by tool ID.

func NewStatusMap

func NewStatusMap(statuses []Status) (m StatusMap)

NewStatusMap indexes statuses by tool ID.

func (StatusMap) AreAllValid

func (m StatusMap) AreAllValid(ids []string) (valid bool)

AreAllValid reports whether every tool ID has a valid status.

func (StatusMap) ExplainIssues

func (m StatusMap) ExplainIssues(ids []string) (message string)

ExplainIssues renders one line per invalid tool, joined with newlines in tool-ID order, or the empty string if all the given tools are valid.

type Tool

type Tool struct {
	ID   string
	Name string

	PinnedVersion    string
	TimeoutSeconds   int
	OutputLimitBytes int64

	Command string
	Version VersionMethod
	Install InstallMethod
}

Tool is a capability joined with its pinned version and execution limits, ready for inspection, installation, or execution.

type VersionMethod

type VersionMethod func(
	ctx context.Context,
	runner CommandRunner,
	environment map[string]string,
	path string,
) (version string, err error)

VersionMethod detects the installed version of the binary at path, using environment for any command it runs. The runner executes version-detection commands.

func DetectByCommand

func DetectByCommand(argument string, extract func(string) (string, error)) (method VersionMethod)

DetectByCommand returns a VersionMethod that runs the tool with argument and extracts the version from its output using extract.

func DetectByGoBinary

func DetectByGoBinary(modulePath string) (method VersionMethod)

DetectByGoBinary returns a VersionMethod that reads the version embedded in a Go binary's build info. ModulePath, if set, must match the binary's main module.