hooks

package
v0.5.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 21, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package hooks manages declarative, user-owned Git hook templates.

Index

Constants

View Source
const (
	BuiltinPreCommit = "builtin:pre-commit"
	BuiltinPrePush   = "builtin:pre-push"
)
View Source
const (
	BuiltinGoPreCommit = "builtin:go-pre-commit"
	BuiltinGoPrePush   = "builtin:go-pre-push"
	BuiltinNodePrePush = "builtin:node-pre-push"
)
View Source
const EventSchemaVersion = 1
View Source
const PolicyVersion = 1

Variables

This section is empty.

Functions

func AppendEvent

func AppendEvent(path string, event Event) error

func AppendEvents added in v0.4.0

func AppendEvents(path string, events []Event) error

func RepositoryRoot

func RepositoryRoot(path string) (string, error)

RepositoryRoot resolves path to the enclosing non-bare Git worktree.

Types

type ActiveProfile added in v0.4.0

type ActiveProfile struct {
	Name   string `json:"name"`
	Order  int    `json:"order"`
	Reason string `json:"reason"`
}

type ApplyOptions

type ApplyOptions struct {
	RepoPath     string
	ConfigPath   string
	WBExecutable string
	Repair       bool
	Force        bool
	Now          func() time.Time
}

type ApplyResult

type ApplyResult struct {
	Report  CheckReport
	Actions []string
}

func Apply

func Apply(options ApplyOptions) (ApplyResult, error)

Apply installs or repairs WB's local shims. It never overwrites unmanaged hook files unless Force is set, and forced replacements are backed up.

type BlockMetrics added in v0.4.0

type BlockMetrics struct {
	ID                string `json:"id"`
	Profile           string `json:"profile"`
	Hook              string `json:"hook"`
	Runs              int    `json:"runs"`
	Failures          int    `json:"failures"`
	TotalDurationMS   int64  `json:"total_duration_ms"`
	AverageDurationMS int64  `json:"average_duration_ms"`
}

type BlockRunResult added in v0.4.0

type BlockRunResult struct {
	ID       string
	Profile  string
	ExitCode int
	Duration time.Duration
}

type CheckReport

type CheckReport struct {
	RepoRoot       string              `json:"repo_root"`
	ManagedPath    string              `json:"managed_path"`
	ConfigPaths    []string            `json:"config_paths,omitempty"`
	Hooks          []string            `json:"hooks"`
	ProfilesAuto   bool                `json:"profiles_auto"`
	ActiveProfiles []ActiveProfile     `json:"active_profiles,omitempty"`
	HookBlocks     map[string][]string `json:"hook_blocks,omitempty"`
	MetricsPath    string              `json:"metrics_path,omitempty"`
	Findings       []Finding           `json:"findings,omitempty"`
}

func Check

func Check(repoPath, configPath, wbExecutable string) (CheckReport, error)

Check validates config, core.hooksPath, generated shims, and executability without changing repository state.

type DailyMetrics

type DailyMetrics struct {
	Date              string `json:"date"`
	Commits           int    `json:"commits"`
	PushAttempts      int    `json:"push_attempts"`
	CommitChecks      int    `json:"commit_checks"`
	HookFailures      int    `json:"hook_failures"`
	HookRuns          int    `json:"hook_runs"`
	TotalDurationMS   int64  `json:"total_duration_ms"`
	AverageDurationMS int64  `json:"average_duration_ms"`
}

type Event

type Event struct {
	SchemaVersion int               `json:"schema_version"`
	Timestamp     time.Time         `json:"timestamp"`
	Repository    string            `json:"repository"`
	Hook          string            `json:"hook"`
	Profile       string            `json:"profile,omitempty"`
	Block         string            `json:"block,omitempty"`
	Action        string            `json:"action"`
	Outcome       string            `json:"outcome"`
	DurationMS    int64             `json:"duration_ms"`
	Commit        string            `json:"commit,omitempty"`
	Branch        string            `json:"branch,omitempty"`
	OS            string            `json:"os"`
	Arch          string            `json:"arch"`
	Labels        map[string]string `json:"labels,omitempty"`
}

func ReadEvents

func ReadEvents(path string) ([]Event, error)

type Finding

type Finding struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Path    string `json:"path,omitempty"`
}

type HookBlock added in v0.4.0

type HookBlock struct {
	ID      string
	Profile string
	Hook    ResolvedHook
}

type HookConfig

type HookConfig struct {
	Template string `yaml:"template" json:"template,omitempty"`
	Disabled bool   `yaml:"disabled" json:"disabled,omitempty"`
}

HookConfig selects a script template for one Git hook. Relative template paths are resolved from the YAML file that declares them.

type MetricsConfig

type MetricsConfig struct {
	Enabled *bool             `yaml:"enabled" json:"enabled,omitempty"`
	Path    string            `yaml:"path" json:"path,omitempty"`
	Labels  map[string]string `yaml:"labels" json:"labels,omitempty"`
}

MetricsConfig controls local hook-event collection. Enabled is a pointer so a repository policy can explicitly override a global true/false value.

type MetricsPolicy

type MetricsPolicy struct {
	Enabled bool
	Path    string
	Labels  map[string]string
}

type MetricsSummary

type MetricsSummary struct {
	From              string         `json:"from"`
	Through           string         `json:"through"`
	RepositoryFilter  string         `json:"repository_filter,omitempty"`
	Commits           int            `json:"commits"`
	PushAttempts      int            `json:"push_attempts"`
	CommitChecks      int            `json:"commit_checks"`
	HookFailures      int            `json:"hook_failures"`
	HookRuns          int            `json:"hook_runs"`
	AverageDurationMS int64          `json:"average_duration_ms"`
	Days              []DailyMetrics `json:"days"`
	Blocks            []BlockMetrics `json:"blocks,omitempty"`
}

func Summarize

func Summarize(events []Event, days int, repositoryFilter string, now time.Time) MetricsSummary

type Policy

type Policy struct {
	RepoRoot           string
	ConfigPaths        []string
	Hooks              map[string]ResolvedHook
	ProfilesAuto       bool
	ProfileSelections  map[string]bool
	ProfileDefinitions map[string]ProfileDefinition
	ActiveProfiles     []ActiveProfile
	Metrics            MetricsPolicy
	ExplicitPath       string
}

Policy is the effective configuration after built-ins, the user's global policy, and the repository policy have been layered in that order.

func LoadPolicy

func LoadPolicy(repoPath, explicitPath string) (Policy, error)

LoadPolicy loads ~/.config/wb/hooks.yaml and .wb/hooks.yaml when present. An explicit path replaces those discovery locations but still layers on top of WB's conservative built-in templates.

type ProfileDefinition added in v0.4.0

type ProfileDefinition struct {
	Name       string
	Order      int
	Detection  ProfileDetection
	Hooks      map[string]ResolvedHook
	ConfigPath string
}

type ProfileDefinitionConfig added in v0.4.0

type ProfileDefinitionConfig struct {
	Order  *int                  `yaml:"order"`
	Detect *ProfileDetection     `yaml:"detect"`
	Hooks  map[string]HookConfig `yaml:"hooks"`
}

ProfileDefinitionConfig describes a language, toolchain, product, or other repository profile. Detection paths are repository-relative and may contain filepath.Glob patterns.

type ProfileDetection added in v0.4.0

type ProfileDetection struct {
	AnyFiles []string `yaml:"any_files" json:"any_files,omitempty"`
	AllFiles []string `yaml:"all_files" json:"all_files,omitempty"`
}

type ProfilesConfig added in v0.4.0

type ProfilesConfig struct {
	Auto        *bool                              `yaml:"auto"`
	Include     []string                           `yaml:"include"`
	Exclude     []string                           `yaml:"exclude"`
	Definitions map[string]ProfileDefinitionConfig `yaml:"definitions"`
}

ProfilesConfig controls automatic detection and profile composition. Each active profile contributes at most one block to each configured hook type.

type ResolvedHook

type ResolvedHook struct {
	Name       string
	Template   string
	Builtin    bool
	Disabled   bool
	ConfigPath string
}

ResolvedHook is a validated hook entry ready to execute.

type RunOptions

type RunOptions struct {
	RepoPath   string
	ConfigPath string
	Hook       string
	Args       []string
	Stdin      io.Reader
	Stdout     io.Writer
	Stderr     io.Writer
	Now        func() time.Time
}

type RunResult

type RunResult struct {
	ExitCode     int
	Duration     time.Duration
	Blocks       []BlockRunResult
	MetricsError error
}

func Run

func Run(options RunOptions) (RunResult, error)

Run executes the configured base and active-profile blocks in the repository root and records compact local events. Hook arguments and streams are passed through unchanged; composed pre-push blocks each receive the complete stdin.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL