Documentation
¶
Overview ¶
Package interfacesnapshot captures and compares the public Cobra command surface without executing commands or contacting runtime services.
Index ¶
Constants ¶
const ( FlagMigrationPending = "pending" FlagMigrationConsumed = "consumed" )
const FlagAliasOfAnnotation = runtimeannotate.AnnotationFlagAliasOf
FlagAliasOfAnnotation records a framework-originated reviewed relationship between a retained compatibility flag and an exact canonical Cobra flag.
const FlagMigrationManifestVersion = 1
const SchemaVersion = 2
Variables ¶
This section is empty.
Functions ¶
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"`
}
Command contains compatibility-relevant command metadata. Path always includes the root command name (for example, "dws chat message send").
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,
- 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 {
Command string `json:"command"`
Legacy FlagMigrationSide `json:"legacy"`
Canonical FlagMigrationSide `json:"canonical"`
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.
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 ¶
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 migrations. Candidate-owned records participate in the lifecycle check, but never authorize their own interface change.
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 ¶
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.
Source Files