deprecation

package
v1.1.4 Latest Latest
Warning

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

Go to latest
Published: May 21, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package deprecation — G4: sunset date computation for per-plugin API entries.

Package deprecation — G7: client-side plugin compatibility checker. CheckPluginCompat is called during nself start to warn when installed plugin versions are below or at a version that has deprecated endpoints.

Package deprecation provides the CLI deprecation warning system.

Usage:

reg, err := deprecation.LoadRegistry("internal/deprecation/registry.yaml")
if err != nil {
    // warn in debug log, do not crash
}
if item, ok := reg.Lookup("nself old-cmd"); ok {
    reg.Warn(os.Stderr, item)
}

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HTTPSunsetHeader added in v1.0.12

func HTTPSunsetHeader(removedIn string) string

HTTPSunsetHeader formats a Sunset HTTP header value for the given removal version. Returns an empty string if removedIn is empty.

func PrintWarnings added in v1.0.12

func PrintWarnings(w io.Writer, warnings []Warning)

PrintWarnings writes all warnings to w, one per line.

func Warn

func Warn(w io.Writer, name, since, replacement, docsURL string)

Warn is a package-level convenience that creates a one-shot warning without needing a Registry. Used for inline deprecations.

Types

type InstalledPlugin added in v1.0.12

type InstalledPlugin struct {
	Name    string
	Version string // SemVer string, e.g. "1.2.0"
}

InstalledPlugin is the caller-supplied record for an installed plugin.

type Item

type Item struct {
	Name        string   `yaml:"name"`
	Type        ItemType `yaml:"type"`
	Since       string   `yaml:"since"`
	Replacement string   `yaml:"replacement"`
	DocsURL     string   `yaml:"docs_url"`
	Phase       int      `yaml:"phase"`
}

Item represents a single deprecated CLI element.

type ItemType

type ItemType string

ItemType classifies the deprecated surface.

const (
	TypeCommand ItemType = "command"
	TypeFlag    ItemType = "flag"
	TypeEnv     ItemType = "env"
)

type PluginEndpoint added in v1.0.12

type PluginEndpoint struct {
	Path         string `yaml:"path"`
	DeprecatedIn string `yaml:"deprecated_in"`
	RemovedIn    string `yaml:"removed_in"`
	Replacement  string `yaml:"replacement"`
	Reason       string `yaml:"reason"`
}

PluginEndpoint represents a single deprecated HTTP endpoint within a plugin.

type PluginEntry added in v1.0.12

type PluginEntry struct {
	Name                string           `yaml:"name"`
	APIVersion          string           `yaml:"api_version"`
	DeprecatedEndpoints []PluginEndpoint `yaml:"deprecated_endpoints"`
}

PluginEntry represents a single plugin's API version entry in registry.yaml.

type PluginRegistry added in v1.0.12

type PluginRegistry struct {
	// contains filtered or unexported fields
}

PluginRegistry holds the per-plugin versioning entries loaded from registry.yaml.

func LoadPluginRegistry added in v1.0.12

func LoadPluginRegistry(path string) (*PluginRegistry, error)

LoadPluginRegistry reads the plugins section from the registry YAML file. Returns an empty PluginRegistry (not nil) on any error.

func (*PluginRegistry) AllPlugins added in v1.0.12

func (pr *PluginRegistry) AllPlugins() []PluginEntry

AllPlugins returns all plugin entries sorted by name.

func (*PluginRegistry) LookupPlugin added in v1.0.12

func (pr *PluginRegistry) LookupPlugin(name string) (PluginEntry, bool)

LookupPlugin returns the PluginEntry for the given plugin name and true if found.

func (*PluginRegistry) SunsetDate added in v1.0.12

func (pr *PluginRegistry) SunsetDate(pluginName string) []SunsetCalendarEntry

SunsetDate returns the SunsetCalendarEntries for a plugin, sorted by RemovedIn. If the plugin is not found in the registry, it returns nil.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds the loaded deprecation entries.

func LoadRegistry

func LoadRegistry(path string) (*Registry, error)

LoadRegistry reads the YAML registry file and returns a Registry. If the file does not exist or fails to parse, it returns an empty Registry and a non-nil error (caller should log in debug mode, not crash).

func (*Registry) IsDeprecated

func (r *Registry) IsDeprecated(name string) bool

IsDeprecated returns true if the given name is in the registry.

func (*Registry) Lookup

func (r *Registry) Lookup(name string) (Item, bool)

Lookup returns the Item for the given name and true if found.

func (*Registry) Warn

func (r *Registry) Warn(w io.Writer, item Item)

Warn writes a deprecation warning for item to w (should be os.Stderr). Format: [DEPRECATED] 'nself <item>' (since v<X.Y.Z>) → use 'nself <replacement>'. Docs: <url>

type SunsetCalendarEntry added in v1.0.12

type SunsetCalendarEntry struct {
	Plugin       string
	Path         string
	DeprecatedIn string
	RemovedIn    string
	Replacement  string
	Reason       string
	SunsetDate   time.Time // zero value when not applicable
}

SunsetCalendarEntry is one row in the human-readable sunset calendar for a plugin.

type Warning added in v1.0.12

type Warning struct {
	Plugin           string
	InstalledVersion string
	Path             string
	DeprecatedIn     string
	RemovedIn        string
	Replacement      string
	Docs             string
}

Warning is a single compatibility warning emitted by CheckPluginCompat.

func CheckPluginCompat added in v1.0.12

func CheckPluginCompat(installed []InstalledPlugin, reg *PluginRegistry) []Warning

CheckPluginCompat compares each installed plugin's version against the registry. It returns warnings for every deprecated endpoint where the installed version is greater than or equal to the version where the deprecation was introduced.

Version comparison is done lexicographically on the SemVer strings. This is accurate for well-formed SemVer within the same major version (which all nSelf plugins are expected to be during the v1.x lifecycle).

func (Warning) String added in v1.0.12

func (w Warning) String() string

String returns the human-readable warning line.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL