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.
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