surface

package
v1.0.4 Latest Latest
Warning

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

Go to latest
Published: Sep 5, 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