precommit

Documentation

Overview

Package precommit detects and manages pre-commit configuration and environment.

Index

• Constants
• func ConfigFile(root string) (string, bool)
• func EnsureTool(r CommandRunner) (string, error)
• func HookInstalled(r CommandRunner, root string) bool
• func InstallHook(r CommandRunner, root string) (string, error)
• func ToolVersion(r CommandRunner) (string, bool)
• type CommandRunner
  • func NewExecRunner() CommandRunner
• type InstallError
  • func (e *InstallError) CategoryNames() []string
  • func (e *InstallError) Error() string
• type Options
• type Result
  • func Check(r CommandRunner, opts Options) (Result, error)

Constants

const (
	// ReasonNoConfig: the repository has no pre-commit config; nothing to check.
	// Paired with OK == true (a clean skip, not a failure).
	ReasonNoConfig = "no_config"
	// ReasonToolMissing: the pre-commit tool is not installed (and was not, or
	// could not be, installed).
	ReasonToolMissing = "tool_missing"
	// ReasonHookMissing: the git pre-commit hook is not initialized.
	ReasonHookMissing = "hook_missing"
	// ReasonRunFailed: the environment is ready but `pre-commit run` failed.
	ReasonRunFailed = "run_failed"
	// ReasonInstallFailed: an auto-install attempt was made but failed. The
	// machine-readable failure categories are carried in
	// Result.InstallFailureCategories. Paired with a non-nil Check error.
	ReasonInstallFailed = "install_failed"
	// ReasonNotInRepo: the working directory is not inside a git repository.
	// Set by the command layer, which never reaches Check.
	ReasonNotInRepo = "not_in_repo"
)

Reason values are stable, machine-readable classifications of a Check outcome, emitted in Result.Reason so scripts/agents can branch without parsing prose. Reason is empty when the environment is fully ready (and any requested run passed). The values are part of the --json contract; see docs/COMMANDS.md.

Functions

func ConfigFile

func ConfigFile(root string) (string, bool)

ConfigFile returns the path to the pre-commit config in root, and whether one exists.

func EnsureTool

func EnsureTool(r CommandRunner) (string, error)

EnsureTool makes sure the pre-commit tool is available, installing it when necessary. It tries each available installer in order, falling through on failure. It returns a human-readable description of any action taken (empty if the tool was already present) and an error if installation was impossible or every attempt failed.

func HookInstalled

func HookInstalled(r CommandRunner, root string) bool

HookInstalled reports whether the repository's pre-commit git hook exists and was generated by the pre-commit tool. root is the repository root; r is used to resolve the real hooks path so git worktrees (where .git is a file) work.

func InstallHook

func InstallHook(r CommandRunner, root string) (string, error)

InstallHook runs `pre-commit install` in root to set up the git hook.

func ToolVersion

func ToolVersion(r CommandRunner) (string, bool)

ToolVersion returns the installed pre-commit version (e.g. "3.7.0") and whether the tool is available.

Types

type CommandRunner

type CommandRunner interface {
	// Look reports whether an executable named name exists on PATH.
	Look(name string) bool
	// Run executes name with args. If dir != "", it is the working directory.
	// It returns the combined stdout+stderr output and any execution error.
	// Use this when the full output (including diagnostics on stderr) is wanted.
	Run(dir, name string, args ...string) (string, error)
	// RunStdout executes name with args like Run, but returns only stdout. Use
	// this for parsing structured output (e.g. version strings) so a warning
	// written to stderr cannot corrupt the parse.
	RunStdout(dir, name string, args ...string) (string, error)
}

CommandRunner runs external commands. It is abstracted so tests can avoid invoking real pre-commit / python binaries.

func NewExecRunner

func NewExecRunner() CommandRunner

NewExecRunner returns a CommandRunner backed by os/exec.

type InstallError

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

InstallError reports a failure to auto-install pre-commit. Beyond the human-readable message it carries the distinct failure categories (in first-seen order) so callers can surface them in structured output (e.g. --json) instead of only emitting prose to stderr.

func (*InstallError) CategoryNames

func (e *InstallError) CategoryNames() []string

CategoryNames returns the failure categories as stable, machine-readable identifiers ("permission" | "network" | "toolchain"), in first-seen order. Unclassified failures are omitted, so the slice may be empty.

func (*InstallError) Error

func (e *InstallError) Error() string

type Options

type Options struct {
	// Root is the git repository root directory.
	Root string
	// AllowInstall permits mutating the environment (installing the tool and/or
	// the git hook) when something is missing.
	AllowInstall bool
	// Run, when true, executes `pre-commit run --all-files` after the environment
	// is confirmed ready.
	Run bool
}

Options controls a Check run.

type Result

type Result struct {
	ConfigFound   bool     `json:"config_found"`
	ToolInstalled bool     `json:"tool_installed"`
	ToolVersion   string   `json:"tool_version,omitempty"`
	HookInstalled bool     `json:"hook_installed"`
	ActionsTaken  []string `json:"actions_taken"`
	RunResult     string   `json:"run_result,omitempty"` // "passed" | "failed" | ""
	RunOutput     string   `json:"run_output,omitempty"` // pre-commit run output when RunResult == "failed"
	OK            bool     `json:"ok"`
	// Reason is a stable, machine-readable classification of the outcome (one of
	// the Reason* constants), or "" when the environment is fully ready.
	Reason string `json:"reason,omitempty"`
	// InstallFailureCategories carries the distinct auto-install failure
	// categories ("permission" | "network" | "toolchain"), in first-seen order,
	// when Reason == ReasonInstallFailed. Empty otherwise.
	InstallFailureCategories []string `json:"install_failure_categories,omitempty"`
}

Result is the structured outcome of a Check. JSON tags match docs/COMMANDS.md.

OK means "nothing blocks committing": it is true when the repository has no pre-commit config (nothing to check), or when the config is present and the tool, hook, and any requested --run all succeeded. Always read OK together with ConfigFound to distinguish "ready" from "no config, skipped".

func Check

func Check(r CommandRunner, opts Options) (Result, error)

Check runs the detection/remediation pipeline and returns a structured Result. It returns a non-nil error only for hard failures (e.g. an install attempt failed). "Not ready" states are reported via Result.OK == false with no error.