cli

Documentation

Overview

Package cli is the testable entry point for the cascade binary. It owns flag parsing, the four-line pipeline assembly (golist.Run → depgraph.Build + changeset.Resolve → g.RevDepClosure), the git-diff io edge, error-to- exit-code mapping, and signal-driven cancellation.

The package is internal/ so external consumers cannot import it; cmd/cascade is the only intended caller. Run is exposed (not main) so the orchestration is testable in-process without subprocess overhead, mirroring the M1 pattern. The git-diff io edge is hooked through a function-variable seam (runGitDiff), mirroring pkg/golist's runGoList from M2.

Exit-code contract:

0 — success (output may be empty if no Go files changed)
1 — flag-parse error or missing required flags or stdin read failure
2 — `git diff` failed (*GitDiffError returned somewhere in the pipeline)
3 — `go list` failed (*golist.ExitError or wrapper)
4 — internal logic error (should never occur — surface as a real bug)
5 — cancelled / interrupted (context cancellation reached the io layer)

The exit-code table is mirrored in three places: this doc, cascade --help's output, and the README's CLI-usage section. Keep in sync.

Index

• Variables
• func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int
• type GitDiffError
  • func (e *GitDiffError) Error() string
  • func (e *GitDiffError) Is(target error) bool
  • func (e *GitDiffError) Unwrap() error

Variables

var ErrGitDiffFailed = errors.New("git diff failed")

ErrGitDiffFailed is returned when `git diff` exits with a non-zero status. Use errors.As(err, &e) with a *GitDiffError to extract the captured stderr and full argv. Mirrors pkg/golist's ErrGoListFailed semantics.

Per EH-15, callers must classify with errors.Is, not string-match against Error() output (AP-13).

Functions

func Run

func Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int

Run is the testable entry point for the cascade CLI. It parses args, runs the pipeline, writes the affected-package set to stdout, and returns the process exit code per the contract documented in the package comment.

stdin is read only when --changed-files=- is passed; otherwise ignored. stderr is used for diagnostic and error output; never for primary output.

Errors are wrapped, never swallowed. Every failure path maps to a specific exit code per the contract; unmapped errors map to exit 4 (internal).

SIGINT and SIGTERM are caught via signal.NotifyContext; cancelling the context kills the in-flight subprocess (git diff or go list) and returns exit 5.

The --help flag prints to stdout per GNU convention; `cascade -h` (or any flag-parse failure) prints to stderr per stdlib flag's default. Both go through the same helpText source so the content is identical.

Types

type GitDiffError

type GitDiffError struct {
	// Cmd is the full argv as passed to exec, in order, for reproduction.
	Cmd []string

	// Dir is the working directory the command was run in (typically the
	// absolutized cfg.root from the cli layer). Mirrors *golist.ExitError.Dir.
	Dir string

	// ExitCode is the subprocess exit code (typically 1 or 128 for `git diff`
	// errors; may be other values).
	ExitCode int

	// Stderr is the captured stderr output, verbatim and untruncated.
	// `git diff`'s stderr on real failures (e.g. "fatal: bad revision
	// 'origin/main'") is small and the diagnostic value is high.
	Stderr string
	// contains filtered or unexported fields
}

GitDiffError captures the diagnostic context when `git diff` exits with a non-zero status. errors.Is(err, ErrGitDiffFailed) returns true; the wrapped *exec.ExitError (when applicable) is reachable via errors.As or by calling Unwrap directly.

The shape mirrors pkg/golist.ExitError so contributors who already know one know the other (EH-08 + EH-16). The Dir field was added to close F-5 in docs/dev/0014-go-quality-audit.md, restoring full cousin-shape parity.

func (*GitDiffError) Error

func (e *GitDiffError) Error() string

Error returns a one-line summary suitable for logging.

func (*GitDiffError) Is

func (e *GitDiffError) Is(target error) bool

Is reports whether target is ErrGitDiffFailed; this is what makes errors.Is(err, ErrGitDiffFailed) true when err is a *GitDiffError.

func (*GitDiffError) Unwrap

func (e *GitDiffError) Unwrap() error

Unwrap returns the wrapped *exec.ExitError when one is captured, else nil. Callers can use errors.As to extract the *exec.ExitError for low-level inspection (e.g. signal info on Unix).