lint

Documentation

Overview

Package lint provides static preflight analysis of mache's Taskfile.

The defect it catches

A "gate" task (verify / audit / sign / lint / check / validate / smells / release / image / build …) that invokes an external binary with NO preflight guard is dangerous: a MISSING tool turns the gate into a cryptic failure — or, when the invocation is swallowed (`… || true`, a script wrapper), a silent no-op that reads as a false PASS (the classic "cargo-deny missing → supply-chain-check silently passes" trap).

The model (declaration-based, no heuristic verdict)

Rather than heuristically infer "is this gate healthy", CheckTaskfile statically enforces that every external binary a gate task invokes is backed by one of go-task's NATIVE guard mechanisms:

1. a task-level `preconditions:` entry — `- sh: command -v <tool>` (with a `msg:` install line);
2. an INLINE guard in the task's cmds — `command -v` / `which` / `type` / `hash <tool>` (e.g. the flamegraphs task's `if ! command -v …`);
3. provisioning in the same task — `go install …/<tool>@…` (e.g. fmt:check installs gofumpt);
4. an artifact-existence assertion — a standalone `test -f`/`test -x` / `[ -f ]`/`[ -x ]` (the capnp false-PASS case: capnp can exit 0 on a plugin error, so the task asserts its output actually exists).

The pass / fail / not-ran ternary then falls out of go-task natively — a failed precondition blocks the task with a loud `msg` and a non-zero exit, so a missing tool can never be a silent no-op. The lint's only job is to prove, statically, that the guard EXISTS.

Parse surface

The Taskfile is decoded straight into `github.com/go-task/task/v3/taskfile/ast` via `go.yaml.in/yaml/v3` (the ast package's own YAML library). We deliberately do NOT use `taskfile.Reader`: the Reader drags in go-getter → the AWS SDK, GCP, gRPC and OpenTelemetry (95 indirect modules vs 12 for the ast package alone) to support remote-include resolution we do not need. `Cmd.Cmd` holds the literal, un-expanded shell string — exactly right for static analysis.

Index

• type Gap
  • func CheckTaskfile(path string) ([]Gap, error)

Types

type Gap

type Gap struct {
	Task string // the gate task's name
	Tool string // the unguarded external binary
	Cmd  string // the command line the binary was found in (first line)
}

Gap is a gate task that invokes an external binary with no preflight guard.

func CheckTaskfile

func CheckTaskfile(path string) ([]Gap, error)

CheckTaskfile parses the Taskfile at path and returns the preflight gaps — gate tasks that invoke an external binary with no guard — sorted by (Task, Tool) for deterministic output.