Documentation
¶
Overview ¶
Package interfacesnapshot captures and compares the public Cobra command surface without executing commands or contacting runtime services.
Index ¶
Constants ¶
const SchemaVersion = 1
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"`
}
Flag contains the stable pflag contract visible at a command node.
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.
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