Help us shape the future of Go! Take the 2026 Go Developer Survey

surface

package
v1.0.10 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package surface captures and compares the stable public Cobra API.

Index

Constants

View Source
const SchemaVersion = 1

Variables

This section is empty.

Functions

func Encode

func Encode(snapshot Snapshot) ([]byte, error)

func PreserveArgumentContract

func PreserveArgumentContract(command *cobra.Command)

PreserveArgumentContract records the current positional contract before a wrapper adds cross-cutting behavior such as structured error classification. The wrapper must not change which argument counts are accepted.

func ValidateTransition

func ValidateTransition(fromVersion, toVersion int, before, after Snapshot, approvals []BreakApproval) error

Types

type BreakApproval

type BreakApproval struct {
	FromVersion  int    `json:"from_version"`
	ToVersion    int    `json:"to_version"`
	ChangeID     string `json:"change_id"`
	BeforeSHA256 string `json:"before_sha256"`
	AfterSHA256  string `json:"after_sha256"`
	Reason       string `json:"reason"`
}

type BreakPolicy

type BreakPolicy struct {
	SchemaVersion int             `json:"schema_version"`
	Changes       []BreakApproval `json:"changes"`
}

func ParseBreakPolicy

func ParseBreakPolicy(data []byte) (BreakPolicy, error)

type Change

type Change struct {
	ID           string `json:"id"`
	Kind         string `json:"kind"`
	Breaking     bool   `json:"breaking"`
	BeforeSHA256 string `json:"before_sha256"`
	AfterSHA256  string `json:"after_sha256"`
}

func Diff

func Diff(before, after Snapshot) []Change

Diff reports every change. Additions are non-breaking. Removals and changes to an incumbent command, alias, argument contract, or flag require an exact approval record.

type Command

type Command struct {
	Path                string   `json:"path"`
	Name                string   `json:"name"`
	Kind                string   `json:"kind"`
	Use                 string   `json:"use"`
	ArgumentPattern     string   `json:"argument_pattern,omitempty"`
	ArgumentContract    string   `json:"argument_contract"`
	Aliases             []string `json:"aliases,omitempty"`
	ArgumentAliases     []string `json:"argument_aliases,omitempty"`
	ValidArguments      []string `json:"valid_arguments,omitempty"`
	GroupID             string   `json:"group_id,omitempty"`
	Runnable            bool     `json:"runnable"`
	Deprecated          string   `json:"deprecated,omitempty"`
	DisableFlagParsing  bool     `json:"disable_flag_parsing,omitempty"`
	TraverseChildren    bool     `json:"traverse_children,omitempty"`
	UnknownFlagsAllowed bool     `json:"unknown_flags_allowed,omitempty"`
	Flags               []Flag   `json:"flags,omitempty"`
}

type Flag

type Flag struct {
	Name       string `json:"name"`
	Scope      string `json:"scope"`
	Shorthand  string `json:"shorthand,omitempty"`
	Type       string `json:"type"`
	Default    string `json:"default"`
	NoOptValue string `json:"no_option_value,omitempty"`
	Required   bool   `json:"required"`
	Deprecated string `json:"deprecated,omitempty"`
	Hidden     bool   `json:"hidden"`
}

type Snapshot

type Snapshot struct {
	SchemaVersion int       `json:"schema_version"`
	Commands      []Command `json:"commands"`
}

Snapshot is a deterministic description of every visible command and flag.

func Build

func Build(root *cobra.Command) Snapshot

Build initializes Cobra's public help command and help flags before walking the tree. Hidden implementation commands are intentionally outside the public contract; hiding a previously visible command is therefore detected as a removal.

func Parse

func Parse(data []byte) (Snapshot, error)

Jump to

Keyboard shortcuts

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