toolrun

Documentation

Overview

Package toolrun defines the Runner interface and its concrete implementation. It is the single choke point for all subprocess execution in archfit.

Index

• type Output
• type Runner
• type RunnerMock
  • func (m *RunnerMock) Detect(ctx context.Context, tool string) (ToolInfo, bool)
  • func (m *RunnerMock) DetectCalls() []struct{ ... }
  • func (m *RunnerMock) Run(ctx context.Context, cmd ToolCmd) (Output, error)
  • func (m *RunnerMock) RunCalls() []struct{ ... }
• type ToolCmd
• type ToolInfo
• type ToolRunner
  • func New() *ToolRunner
  • func (r *ToolRunner) Detect(_ context.Context, tool string) (ToolInfo, bool)
  • func (r *ToolRunner) Run(ctx context.Context, cmd ToolCmd) (Output, error)

Types

type Output

type Output struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
}

Output holds the result of a subprocess invocation. A non-zero exit code is recorded in ExitCode, not returned as an error. Error is reserved for exec failures (binary not found, I/O error, etc.).

type Runner

type Runner interface {
	// Detect checks whether tool is available on PATH and returns its info.
	// Returns (ToolInfo{}, false) if the tool is not found.
	Detect(ctx context.Context, tool string) (ToolInfo, bool)

	// Run executes cmd and returns its captured output.
	// A non-zero exit code is recorded in Output.ExitCode — it is NOT an error.
	// Error is returned only for exec-level failures (binary missing, I/O error).
	Run(ctx context.Context, cmd ToolCmd) (Output, error)
}

Runner is the process boundary for all external tool invocations. Adapters (extract/*, history/git) depend on this interface so they can be tested with a mock without touching os/exec.

type RunnerMock

type RunnerMock struct {
	// DetectFunc mocks the Detect method.
	DetectFunc func(ctx context.Context, tool string) (ToolInfo, bool)

	// RunFunc mocks the Run method.
	RunFunc func(ctx context.Context, cmd ToolCmd) (Output, error)
	// contains filtered or unexported fields
}

RunnerMock is a mock implementation of Runner for testing.

func TestSomething(t *testing.T) {
    runner := &toolrun.RunnerMock{
        DetectFunc: func(ctx context.Context, tool string) (ToolInfo, bool) { ... },
        RunFunc:    func(ctx context.Context, cmd ToolCmd) (Output, error) { ... },
    }
    ...
}

func (*RunnerMock) Detect

func (m *RunnerMock) Detect(ctx context.Context, tool string) (ToolInfo, bool)

Detect calls DetectFunc.

func (*RunnerMock) DetectCalls

func (m *RunnerMock) DetectCalls() []struct {
	Ctx  context.Context
	Tool string
}

DetectCalls returns all calls that were made to Detect.

func (*RunnerMock) Run

func (m *RunnerMock) Run(ctx context.Context, cmd ToolCmd) (Output, error)

Run calls RunFunc.

func (*RunnerMock) RunCalls

func (m *RunnerMock) RunCalls() []struct {
	Ctx context.Context
	Cmd ToolCmd
}

RunCalls returns all calls that were made to Run.

type ToolCmd

type ToolCmd struct {
	Name    string
	Args    []string
	Env     []string
	Timeout time.Duration
	// WorkDir sets the working directory for the subprocess.
	// When empty the current process directory is used.
	WorkDir string
}

ToolCmd describes a subprocess invocation.

type ToolInfo

type ToolInfo struct {
	Name    string
	Path    string
	Version string
}

ToolInfo describes a detected external tool.

type ToolRunner

type ToolRunner struct{}

ToolRunner is the concrete Runner implementation. It is the only type in the codebase that may use os/exec.

func New

func New() *ToolRunner

New returns a new ToolRunner.

func (*ToolRunner) Detect

func (r *ToolRunner) Detect(_ context.Context, tool string) (ToolInfo, bool)

Detect uses exec.LookPath to find tool on PATH.

func (*ToolRunner) Run

func (r *ToolRunner) Run(ctx context.Context, cmd ToolCmd) (Output, error)

Run executes cmd.Name with cmd.Args. It pins LC_ALL=C and TZ=UTC for deterministic output, then appends any caller-supplied cmd.Env on top. If cmd.Timeout > 0 a deadline is applied via context.WithTimeout. Non-zero exit codes are recorded in Output.ExitCode, not returned as errors.