modernize

Documentation

Overview

Package modernize detects and fixes known YAML config anti-patterns in workflow configuration files.

Index

• type Change
• type Finding
• type ManifestRule
  • func (mr ManifestRule) MustToRule() Rule
  • func (mr ManifestRule) ToRule() (Rule, error)
  • func (mr ManifestRule) Validate() error
• type Rule
  • func AllRules() []Rule
  • func FilterRules(rules []Rule, include, exclude string) []Rule
  • func LoadRulesFromDir(pluginDir string) ([]Rule, error)

Types

type Change

type Change struct {
	RuleID      string `json:"rule_id"`
	Line        int    `json:"line"`
	Description string `json:"description"`
}

Change represents a modification applied by a rule's Fix function.

type Finding

type Finding struct {
	RuleID  string `json:"rule_id"`
	Line    int    `json:"line"`
	Message string `json:"message"`
	Fixable bool   `json:"fixable"`
}

Finding represents a single issue detected by a modernize rule.

type ManifestRule

type ManifestRule struct {
	// ID is a unique, kebab-case identifier for the rule (e.g., "myplugin-rename-type").
	ID string `json:"id"`
	// Description is a human-readable summary of what the rule detects/fixes.
	Description string `json:"description"`
	// Severity is "error" or "warning" (default: "warning").
	Severity string `json:"severity,omitempty"`
	// Message overrides the auto-generated finding message.
	Message string `json:"message,omitempty"`

	// OldModuleType and NewModuleType trigger a module type rename rule.
	// When set, the rule detects any module with type == OldModuleType
	// and, when fixed, renames it to NewModuleType.
	OldModuleType string `json:"oldModuleType,omitempty"`
	NewModuleType string `json:"newModuleType,omitempty"`

	// OldStepType and NewStepType trigger a step type rename rule.
	// When set, the rule detects any pipeline step with type == OldStepType
	// and, when fixed, renames it to NewStepType.
	OldStepType string `json:"oldStepType,omitempty"`
	NewStepType string `json:"newStepType,omitempty"`

	// ModuleType and OldKey/NewKey trigger a module config key rename rule.
	// Detects modules of the given type that have OldKey in their config
	// and, when fixed, renames the key to NewKey.
	ModuleType string `json:"moduleType,omitempty"`

	// StepType and OldKey/NewKey trigger a step config key rename rule.
	// Detects steps of the given type that have OldKey in their config
	// and, when fixed, renames the key to NewKey.
	StepType string `json:"stepType,omitempty"`

	// OldKey is the config key to detect (used with ModuleType or StepType).
	OldKey string `json:"oldKey,omitempty"`
	// NewKey is the replacement config key (used with ModuleType or StepType).
	NewKey string `json:"newKey,omitempty"`
}

ManifestRule is a JSON-serializable modernize rule that external plugins can declare in their plugin.json manifest under the "modernizeRules" key. It supports the most common migration patterns: renaming module types, renaming step types, and renaming config keys within a specific module or step type.

Example plugin.json snippet:

{
  "modernizeRules": [
    {
      "id": "myplugin-rename-type",
      "description": "Rename old.module.type to new.module.type",
      "severity": "error",
      "oldModuleType": "old.module.type",
      "newModuleType": "new.module.type"
    },
    {
      "id": "myplugin-rename-key",
      "description": "Rename old_key to new_key in my.module config",
      "severity": "warning",
      "moduleType": "my.module",
      "oldKey": "old_key",
      "newKey": "new_key"
    }
  ]
}

func (ManifestRule) MustToRule

func (mr ManifestRule) MustToRule() Rule

MustToRule is like ToRule but panics on misconfiguration. It is intended for use in plugin initialisation code where a malformed rule is a programming error.

func (ManifestRule) ToRule

func (mr ManifestRule) ToRule() (Rule, error)

ToRule converts a ManifestRule into a Rule with appropriate Check and Fix functions. Returns an error if the rule is misconfigured (see Validate).

func (ManifestRule) Validate

func (mr ManifestRule) Validate() error

Validate returns an error if the ManifestRule is misconfigured.

type Rule

type Rule struct {
	ID          string
	Description string
	Severity    string // "error" or "warning"
	Check       func(root *yaml.Node, raw []byte) []Finding
	Fix         func(root *yaml.Node) []Change
}

Rule defines a modernize transformation rule.

func AllRules

func AllRules() []Rule

AllRules returns all registered modernize rules.

func FilterRules

func FilterRules(rules []Rule, include, exclude string) []Rule

FilterRules filters the rule list based on include/exclude flags.

func LoadRulesFromDir

func LoadRulesFromDir(pluginDir string) ([]Rule, error)

LoadRulesFromDir scans pluginDir for subdirectories containing a plugin.json manifest with a "modernizeRules" field, converts each manifest rule to a Rule, and returns the combined slice. Subdirectories with missing or malformed manifests are silently skipped. Returns an error only if pluginDir cannot be read at all.