lint

Documentation

Overview

Package lint provides a per-language linter/auto-fix cycle that can be invoked after hawk writes or edits a file. Linters are looked up by language (derived from the file extension) and run against a single file. A non-zero linter exit surfaces the captured output so an agent can auto-fix the reported issues.

The package is intentionally self-contained: it shells out to well-known per-language tools (go vet/gofmt, eslint, ruff) and also supports custom linters supplied declaratively via Config.Custom.

Index

• func LanguageForExt(ext string) string
• func LanguageForFile(file string) string
• func ParseCustomFlag(value string) (lang, cmd string, ok bool)
• type Config
• type Linter
  • func LinterFor(lang string, cfg Config) Linter
• type Result
  • func RunLint(ctx context.Context, file string, cfg Config) Result

Functions

func LanguageForExt

func LanguageForExt(ext string) string

LanguageForExt maps a file extension (including the leading dot) to a canonical language key. Returns "" when the extension is unknown.

func LanguageForFile

func LanguageForFile(file string) string

LanguageForFile resolves the language key for a file path.

func ParseCustomFlag

func ParseCustomFlag(value string) (lang, cmd string, ok bool)

ParseCustomFlag parses a "--lint 'lang: cmd'" style value into a (lang, cmd) pair. Returns ok=false when the value is malformed (missing colon or empty lang/cmd). Exposed so the CLI flag layer can populate Config.Custom.

Types

type Config

type Config struct {
	// Enabled gates the whole feature. When false, RunLint is a no-op.
	Enabled bool
	// Custom maps a language key to a shell command template. The token
	// "{file}" in the command is replaced with the absolute file path. If no
	// "{file}" token is present, the file path is appended as a final argument.
	// Custom entries take precedence over the built-in linter for a language.
	Custom map[string]string
	// Timeout overrides defaultTimeout when non-zero.
	Timeout time.Duration
}

Config controls which linters run. The zero value disables linting, which keeps the post-write hook off by default so users are not surprised.

type Linter

type Linter interface {
	// Name returns a human-readable linter name.
	Name() string
	// Lint runs the linter against file and reports the result.
	Lint(ctx context.Context, file string) Result
}

Linter runs against a single file and returns a Result. Implementations must be safe to call concurrently.

func LinterFor

func LinterFor(lang string, cfg Config) Linter

LinterFor returns the Linter to use for the given language under cfg, or nil when no linter is configured. Custom commands win over built-ins.

type Result

type Result struct {
	// Language is the resolved language key (e.g. "go", "js", "python").
	Language string
	// Linter is a human-readable name of the linter that ran.
	Linter string
	// Output is the combined stdout/stderr of the linter, trimmed.
	Output string
	// OK reports whether the file passed (linter exited zero / produced no
	// actionable findings). When false, Output carries the findings.
	OK bool
	// Ran reports whether any linter was actually executed. It is false when
	// no linter is configured for the language or the underlying tool is not
	// installed.
	Ran bool
}

Result is the outcome of running a linter against a file.

func RunLint

func RunLint(ctx context.Context, file string, cfg Config) Result

RunLint resolves and runs the linter for file under cfg. When linting is disabled or no linter is configured/installed, it returns a Result with Ran=false and OK=true so callers can treat it as a no-op.