interfacesnapshot

package
v1.0.63 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package interfacesnapshot captures and compares the public Cobra command surface without executing commands or contacting runtime services.

Index

Constants

View Source 
const (
	CommandMigrationPending  = "pending"
	CommandMigrationConsumed = "consumed"

	CommandMigrationMove           = "command_move"
	CommandMigrationFlagExtraction = "flag_extraction"
	CommandMigrationAvailability   = "schema_availability_hardening"
)
View Source 
const (
	FlagMigrationPending  = "pending"
	FlagMigrationConsumed = "consumed"

	FlagMigrationRename             = "flag_rename"
	FlagMigrationRequirednessChange = "requiredness_change"
)
View Source 
const CommandMigrationManifestVersion = 1
View Source 
const FlagAliasOfAnnotation = runtimeannotate.AnnotationFlagAliasOf

FlagAliasOfAnnotation records a framework-originated reviewed relationship between a retained compatibility flag and an exact canonical Cobra flag.

View Source 
const FlagMigrationManifestVersion = 1
View Source 
const SchemaVersion = 3

Variables

This section is empty.

Functions

func Write 

func Write(w io.Writer, snapshot Snapshot) error

Write emits canonical, indented JSON with a trailing newline.

Types

type Change 

type Change struct {
	Kind   string `json:"kind"`
	Path   string `json:"path"`
	Flag   string `json:"flag,omitempty"`
	Before string `json:"before,omitempty"`
	After  string `json:"after,omitempty"`
}

Change describes one compatibility decision. Before and After are concise, human-readable values intended for CI annotations.

type Command 

type Command struct {
	Path            string          `json:"path"`
	Runnable        bool            `json:"runnable"`
	Hidden          bool            `json:"hidden"`
	Deprecated      string          `json:"deprecated,omitempty"`
	Aliases         []string        `json:"aliases"`
	LocalFlags      []Flag          `json:"local_flags"`
	InheritedFlags  []Flag          `json:"inherited_flags"`
	BoolConstParams map[string]bool `json:"bool_const_params,omitempty"`
}

Command contains compatibility-relevant command metadata. Path always includes the root command name (for example, "dws chat message send").

type CommandAvailabilityChange added in v1.0.60 

type CommandAvailabilityChange struct {
	Before string `json:"before"`
	After  string `json:"after"`
}

type CommandMigration added in v1.0.59 

type CommandMigration struct {
	Kind        string                 `json:"kind"`
	Legacy      CommandMigrationSide   `json:"legacy"`
	Replacement CommandMigrationSide   `json:"replacement"`
	LegacyFlag  CommandMigrationFlag   `json:"legacy_flag"`
	Schema      CommandMigrationSchema `json:"schema"`
	State       string                 `json:"state"`
	Reason      string                 `json:"reason"`
}

func AuthorizeCommandMigrations added in v1.0.59 

func AuthorizeCommandMigrations(
	current Snapshot,
	references map[string]Snapshot,
	authority CommandMigrationManifest,
	candidate CommandMigrationManifest,
) ([]CommandMigration, error)

type CommandMigrationFlag added in v1.0.59 

type CommandMigrationFlag struct {
	Name   string             `json:"name,omitempty"`
	Before FlagMigrationState `json:"before"`
	After  FlagMigrationState `json:"after"`
}

type CommandMigrationManifest added in v1.0.59 

type CommandMigrationManifest struct {
	Version    int                `json:"version"`
	Migrations []CommandMigration `json:"migrations"`
}

CommandMigrationManifest governs compatibility-preserving surface moves that cannot be represented as an in-command flag rename. The merge-base owns the authorization; the candidate copy is only a lifecycle receipt.

func ReadCommandMigrationManifest added in v1.0.59 

func ReadCommandMigrationManifest(r io.Reader) (CommandMigrationManifest, error)

func (CommandMigrationManifest) Validate added in v1.0.59 

func (m CommandMigrationManifest) Validate() error

type CommandMigrationSchema added in v1.0.59 

type CommandMigrationSchema struct {
	ProductID         string                      `json:"product_id"`
	SourceToolID      string                      `json:"source_tool_id"`
	ReplacementToolID string                      `json:"replacement_tool_id"`
	Parameters        []CommandParameterMigration `json:"parameters"`
	Availability      *CommandAvailabilityChange  `json:"availability,omitempty"`
}

type CommandMigrationSide added in v1.0.59 

type CommandMigrationSide struct {
	Command string                `json:"command"`
	Before  CommandMigrationState `json:"before"`
	After   CommandMigrationState `json:"after"`
}

type CommandMigrationState added in v1.0.59 

type CommandMigrationState struct {
	Present  bool `json:"present"`
	Runnable bool `json:"runnable,omitempty"`
	Hidden   bool `json:"hidden,omitempty"`
}

type CommandParameterMigration added in v1.0.59 

type CommandParameterMigration struct {
	From                string                      `json:"from"`
	To                  string                      `json:"to,omitempty"`
	ReplacementConstant *CommandReplacementConstant `json:"replacement_constant,omitempty"`
}

type CommandReplacementConstant added in v1.0.59 

type CommandReplacementConstant struct {
	Property string `json:"property"`
	Value    bool   `json:"value"`
}

type Comparison 

type Comparison struct {
	Reference  string   `json:"reference"`
	Compatible bool     `json:"compatible"`
	Blocking   []Change `json:"blocking"`
	Additions  []Change `json:"additions"`
}

Comparison is the result for one reference snapshot.

func Compare 

func Compare(current, baseline Snapshot, reference string) Comparison

Compare enforces the deliberately small admission policy:

  • every previously accepted command path must still resolve to a runnable, visible-compatible target (a rename may preserve the old path as an alias),
  • flags accepted at each command path may not disappear, change type, or become required; an existing path may not gain a new required flag,
  • once bool ConstParams evidence exists, its exact property/value map is a durable contract; adding the first evidence to an older snapshot remains a silent bootstrap,
  • new commands and flags are allowed.

The single exception to the type rule is an individually reviewed migration listed in reviewedFlagTypeChanges, and only when nothing else about the flag changed. See reviewed.go.

Comparing the effective local + inherited set is intentional. It catches a persistent flag whose scope is accidentally narrowed to its declaring command, while allowing a local flag to move to an ancestor without breaking the old invocation path.

type Flag 

type Flag struct {
	Name       string `json:"name"`
	Shorthand  string `json:"shorthand,omitempty"`
	Type       string `json:"type"`
	Default    string `json:"default"`
	NoOpt      string `json:"no_opt,omitempty"`
	Required   bool   `json:"required"`
	Hidden     bool   `json:"hidden"`
	Deprecated string `json:"deprecated,omitempty"`
	AliasOf    string `json:"alias_of,omitempty"`
	// contains filtered or unexported fields
}

Flag contains the stable pflag contract visible at a command node.

type FlagMigration added in v1.0.58 

type FlagMigration struct {
	Kind      string             `json:"kind,omitempty"`
	Command   string             `json:"command"`
	Legacy    FlagMigrationSide  `json:"legacy"`
	Canonical FlagMigrationSide  `json:"canonical"`
	Flag      *FlagMigrationSide `json:"flag,omitempty"`
	State     string             `json:"state"`
	Reason    string             `json:"reason"`
}

func AuthorizeFlagMigrations added in v1.0.58 

func AuthorizeFlagMigrations(
	current Snapshot,
	references map[string]Snapshot,
	authority FlagMigrationManifest,
	candidate FlagMigrationManifest,
) ([]FlagMigration, error)

AuthorizeFlagMigrations validates both snapshots and manifests, enforces the base-owned migration lifecycle, and returns only approvals that may authorize the current exact interface transition. A non-empty lifecycle requires both a main/merge-base authority reference and a stable reference. Candidate-added records never appear in the returned authorization set.

func (FlagMigration) EffectiveKind added in v1.0.60 

func (m FlagMigration) EffectiveKind() string

EffectiveKind keeps manifests written before kinds were introduced valid. An omitted kind is the original flag rename primitive.

type FlagMigrationManifest added in v1.0.58 

type FlagMigrationManifest struct {
	Version    int             `json:"version"`
	Migrations []FlagMigration `json:"migrations"`
}

func ReadFlagMigrationManifest added in v1.0.58 

func ReadFlagMigrationManifest(r io.Reader) (FlagMigrationManifest, error)

func (FlagMigrationManifest) Validate added in v1.0.58 

func (m FlagMigrationManifest) Validate() error

type FlagMigrationSide added in v1.0.58 

type FlagMigrationSide struct {
	Name   string             `json:"name"`
	Before FlagMigrationState `json:"before"`
	After  FlagMigrationState `json:"after"`
}

type FlagMigrationState added in v1.0.58 

type FlagMigrationState struct {
	Present   bool   `json:"present"`
	Type      string `json:"type,omitempty"`
	Required  bool   `json:"required,omitempty"`
	Hidden    bool   `json:"hidden,omitempty"`
	Shorthand string `json:"shorthand,omitempty"`
	NoOpt     string `json:"no_opt,omitempty"`
	Scope     string `json:"scope,omitempty"`
	AliasOf   string `json:"alias_of,omitempty"`
}

type Report 

type Report struct {
	Compatible  bool         `json:"compatible"`
	Comparisons []Comparison `json:"comparisons"`
}

Report combines comparisons against independently supplied compatibility references, normally the PR merge-base and the latest stable GA release.

func CompareAll 

func CompareAll(current Snapshot, references map[string]Snapshot) Report

CompareAll compares current against every named reference in one pass. Additions are reported but remain compatible.

func CompareAllWithFlagMigrations added in v1.0.58 

func CompareAllWithFlagMigrations(
	current Snapshot,
	references map[string]Snapshot,
	authority FlagMigrationManifest,
	candidate FlagMigrationManifest,
) (Report, error)

CompareAllWithFlagMigrations applies the ordinary compatibility policy and then consumes only exact, merge-base-owned flag rename or requiredness migrations. Candidate-owned records participate in the lifecycle check, but never authorize their own interface change.

func CompareAllWithInterfaceMigrations added in v1.0.59 

func CompareAllWithInterfaceMigrations(
	current Snapshot,
	references map[string]Snapshot,
	flagAuthority FlagMigrationManifest,
	flagCandidate FlagMigrationManifest,
	commandAuthority CommandMigrationManifest,
	commandCandidate CommandMigrationManifest,
) (Report, error)

CompareAllWithInterfaceMigrations applies both migration families to one ordinary report, so the two ledgers cannot mask each other's unrelated findings.

type Rules 

type Rules struct {
	ExcludedCommandSubtrees []string `json:"excluded_command_subtrees"`
	ExcludedFlags           []string `json:"excluded_flags"`
}

Rules records the noise filtering contract in every snapshot. A future rule change is therefore visible instead of silently changing comparison scope.

type Snapshot 

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

Snapshot is a deterministic representation of a Cobra command tree.

func Capture 

func Capture(root *cobra.Command) Snapshot

Capture walks root without rendering help or executing any command. Both hidden compatibility commands and hidden flags are retained unless they are covered by the explicit framework-noise rules above.

func Read 

func Read(r io.Reader) (Snapshot, error)

Read decodes and validates a snapshot. Unknown fields are rejected so a comparison never silently ignores a newer contract it does not understand.

func (Snapshot) Validate 

func (s Snapshot) Validate() error

Validate checks the invariants needed by the comparison algorithm.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.