Skip to content

scripts

import "github.com/santosr2/uptool/scripts"

Command gen_integrations generates the all.go file that imports all integrations. This ensures that adding a new integration doesn't require manual updates.

Usage:

go run scripts/gen_integrations.go

Or via go generate:

go generate ./internal/integrations

Index

uptool

import "github.com/santosr2/uptool/cmd/uptool"

uptool is a manifest-first dependency updater for multiple ecosystems. It scans repositories for dependency manifest files \(package.json, Chart.yaml, .pre\-commit\-config.yaml, etc.\), checks for available updates, and rewrites manifests with new versions while preserving formatting.

Index

datasource

import "github.com/santosr2/uptool/internal/datasource"

Package datasource provides a unified interface for querying package registries. This abstraction allows multiple integrations to share the same registry client.

Index

func List

func List() []string

List returns all registered datasource names.

func Register

func Register(ds Datasource)

Register adds a datasource to the global registry.

type Datasource

Datasource represents a package registry or version source.

type Datasource interface {
    // Name returns the datasource identifier (e.g., "npm", "pypi", "github-releases")
    Name() string

    // GetLatestVersion returns the latest stable version for a package.
    GetLatestVersion(ctx context.Context, pkg string) (string, error)

    // GetVersions returns all available versions for a package.
    GetVersions(ctx context.Context, pkg string) ([]string, error)

    // GetPackageInfo returns detailed information about a package.
    GetPackageInfo(ctx context.Context, pkg string) (*PackageInfo, error)
}

func Get

func Get(name string) (Datasource, error)

Get returns a datasource by name.

type GitHubDatasource

GitHubDatasource implements the Datasource interface for GitHub Releases.

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

func NewGitHubDatasource

func NewGitHubDatasource() *GitHubDatasource

NewGitHubDatasource creates a new GitHub datasource.

func \(\*GitHubDatasource\) GetLatestVersion

func (d *GitHubDatasource) GetLatestVersion(ctx context.Context, pkg string) (string, error)

GetLatestVersion returns the latest stable release for a GitHub repository.

func \(\*GitHubDatasource\) GetPackageInfo

func (d *GitHubDatasource) GetPackageInfo(ctx context.Context, pkg string) (*PackageInfo, error)

GetPackageInfo returns detailed information about a GitHub repository's releases.

func \(\*GitHubDatasource\) GetVersions

func (d *GitHubDatasource) GetVersions(ctx context.Context, pkg string) ([]string, error)

GetVersions returns all available releases for a GitHub repository.

func \(\*GitHubDatasource\) Name

func (d *GitHubDatasource) Name() string

Name returns the datasource identifier.

type HelmDatasource

HelmDatasource implements the Datasource interface for Helm chart repositories.

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

func NewHelmDatasource

func NewHelmDatasource() *HelmDatasource

NewHelmDatasource creates a new Helm datasource.

func \(\*HelmDatasource\) GetLatestVersion

func (d *HelmDatasource) GetLatestVersion(ctx context.Context, pkg string) (string, error)

GetLatestVersion returns the latest stable version for a Helm chart.

func \(\*HelmDatasource\) GetPackageInfo

func (d *HelmDatasource) GetPackageInfo(ctx context.Context, pkg string) (*PackageInfo, error)

GetPackageInfo returns detailed information about a Helm chart.

func \(\*HelmDatasource\) GetVersions

func (d *HelmDatasource) GetVersions(ctx context.Context, pkg string) ([]string, error)

GetVersions returns all available versions for a Helm chart.

func \(\*HelmDatasource\) Name

func (d *HelmDatasource) Name() string

Name returns the datasource identifier.

type NPMDatasource

NPMDatasource implements the Datasource interface for the npm registry.

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

func NewNPMDatasource

func NewNPMDatasource() *NPMDatasource

NewNPMDatasource creates a new npm datasource.

func \(\*NPMDatasource\) GetLatestVersion

func (d *NPMDatasource) GetLatestVersion(ctx context.Context, pkg string) (string, error)

GetLatestVersion returns the latest stable version for an npm package.

func \(\*NPMDatasource\) GetPackageInfo

func (d *NPMDatasource) GetPackageInfo(ctx context.Context, pkg string) (*PackageInfo, error)

GetPackageInfo returns detailed information about an npm package.

func \(\*NPMDatasource\) GetVersions

func (d *NPMDatasource) GetVersions(ctx context.Context, pkg string) ([]string, error)

GetVersions returns all available versions for an npm package.

func \(\*NPMDatasource\) Name

func (d *NPMDatasource) Name() string

Name returns the datasource identifier.

type PackageInfo

PackageInfo contains metadata about a package.

type PackageInfo struct {
    Name        string
    Description string
    Homepage    string
    Repository  string
    Versions    []VersionInfo
}

type TerraformDatasource

TerraformDatasource implements the Datasource interface for the Terraform Registry.

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

func NewTerraformDatasource

func NewTerraformDatasource() *TerraformDatasource

NewTerraformDatasource creates a new Terraform datasource.

func \(\*TerraformDatasource\) GetLatestVersion

func (d *TerraformDatasource) GetLatestVersion(ctx context.Context, pkg string) (string, error)

GetLatestVersion returns the latest stable version for a Terraform module or provider.

func \(\*TerraformDatasource\) GetPackageInfo

func (d *TerraformDatasource) GetPackageInfo(ctx context.Context, pkg string) (*PackageInfo, error)

GetPackageInfo returns detailed information about a Terraform module or provider.

func \(\*TerraformDatasource\) GetVersions

func (d *TerraformDatasource) GetVersions(ctx context.Context, pkg string) ([]string, error)

GetVersions returns all available versions for a Terraform module or provider.

func \(\*TerraformDatasource\) Name

func (d *TerraformDatasource) Name() string

Name returns the datasource identifier.

type VersionInfo

VersionInfo contains metadata about a specific version.

type VersionInfo struct {
    Version      string
    PublishedAt  string
    IsPrerelease bool
    Deprecated   bool
}

engine

import "github.com/santosr2/uptool/internal/engine"

Package engine provides the core orchestration layer for uptool. It manages integration registration, manifest scanning, update planning, and update application. The Engine coordinates concurrent operations across multiple integrations while handling errors and logging.

Package engine provides the core orchestration layer for uptool's dependency scanning and updating. It defines the fundamental types and interfaces used across all integrations, including Manifest, Dependency, UpdatePlan, and the Integration interface.

Index

type ApplyResult

ApplyResult contains the outcome of applying updates.

type ApplyResult struct {
    Manifest     *Manifest `json:"manifest"`
    ManifestDiff string    `json:"manifest_diff,omitempty"`
    LockfileDiff string    `json:"lockfile_diff,omitempty"`
    Errors       []string  `json:"errors,omitempty"`
    Applied      int       `json:"applied"`
    Failed       int       `json:"failed"`
}

type Dependency

Dependency represents a single dependency in a manifest.

type Dependency struct {
    Name           string `json:"name"`
    CurrentVersion string `json:"current_version"`
    Constraint     string `json:"constraint,omitempty"`
    Type           string `json:"type"` // direct, dev, peer, optional
    Registry       string `json:"registry,omitempty"`
}

type Engine

Engine orchestrates the scan, plan, and update operations.

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

func NewEngine

func NewEngine(logger *slog.Logger) *Engine

NewEngine creates a new engine with the given integrations.

func \(\*Engine\) GetIntegration

func (e *Engine) GetIntegration(name string) (Integration, bool)

GetIntegration retrieves a registered integration by name.

func \(\*Engine\) ListIntegrations

func (e *Engine) ListIntegrations() []string

ListIntegrations returns all registered integration names.

func \(\*Engine\) Plan

func (e *Engine) Plan(ctx context.Context, manifests []*Manifest) (*PlanResult, error)

Plan generates update plans for all manifests.

func \(\*Engine\) Register

func (e *Engine) Register(integration Integration)

Register adds an integration to the engine.

func \(\*Engine\) Scan

func (e *Engine) Scan(ctx context.Context, repoRoot string, only, exclude []string) (*ScanResult, error)

Scan discovers all manifests across registered integrations.

func \(\*Engine\) Update

func (e *Engine) Update(ctx context.Context, plans []*UpdatePlan, dryRun bool) (*UpdateResult, error)

Update applies update plans.

type Impact

Impact describes the severity of an update.

type Impact string

Impact levels for update severity

const (
    ImpactNone  Impact = "none"
    ImpactPatch Impact = "patch"
    ImpactMinor Impact = "minor"
    ImpactMajor Impact = "major"
)

type Integration

Integration defines the interface for ecosystem integrations.

type Integration interface {
    // Name returns the integration identifier
    Name() string

    // Detect finds manifest files for this integration
    Detect(ctx context.Context, repoRoot string) ([]*Manifest, error)

    // Plan determines available updates for a manifest
    Plan(ctx context.Context, manifest *Manifest) (*UpdatePlan, error)

    // Apply executes the update plan
    Apply(ctx context.Context, plan *UpdatePlan) (*ApplyResult, error)

    // Validate checks if changes are valid (optional)
    Validate(ctx context.Context, manifest *Manifest) error
}

type IntegrationPolicy

IntegrationPolicy contains policy settings that apply to a specific integration.

type IntegrationPolicy struct {
    Custom          map[string]interface{} `yaml:",inline" json:"custom,omitempty"`
    Update          string                 `yaml:"update" json:"update"`
    Cadence         string                 `yaml:"cadence,omitempty" json:"cadence,omitempty"`
    Enabled         bool                   `yaml:"enabled" json:"enabled"`
    AllowPrerelease bool                   `yaml:"allow_prerelease" json:"allow_prerelease"`
    Pin             bool                   `yaml:"pin" json:"pin"`
}

type Manifest

Manifest represents a dependency manifest file.

type Manifest struct {
    Metadata     map[string]interface{} `json:"metadata,omitempty"`
    Path         string                 `json:"path"`
    Type         string                 `json:"type"`
    Dependencies []Dependency           `json:"dependencies"`
    Content      []byte                 `json:"-"`
}

type PlanResult

PlanResult aggregates all update plans.

type PlanResult struct {
    Plans     []*UpdatePlan `json:"plans"`
    Timestamp time.Time     `json:"timestamp"`
    Errors    []string      `json:"errors,omitempty"`
}

type ScanResult

ScanResult aggregates all discovered manifests.

type ScanResult struct {
    Manifests []*Manifest `json:"manifests"`
    Timestamp time.Time   `json:"timestamp"`
    RepoRoot  string      `json:"repo_root"`
    Errors    []string    `json:"errors,omitempty"`
}

type Update

Update represents a planned update for a dependency.

type Update struct {
    Dependency    Dependency `json:"dependency"`
    TargetVersion string     `json:"target_version"`
    Impact        string     `json:"impact"` // patch, minor, major
    ChangelogURL  string     `json:"changelog_url,omitempty"`
    Breaking      bool       `json:"breaking"`
}

type UpdatePlan

UpdatePlan describes planned updates for a manifest.

type UpdatePlan struct {
    Manifest *Manifest `json:"manifest"`
    Strategy string    `json:"strategy"`
    Updates  []Update  `json:"updates"`
}

type UpdateResult

UpdateResult aggregates all apply results.

type UpdateResult struct {
    Results   []*ApplyResult `json:"results"`
    Timestamp time.Time      `json:"timestamp"`
    Errors    []string       `json:"errors,omitempty"`
}

integrations

import "github.com/santosr2/uptool/internal/integrations"

Package integrations provides metadata about available integrations.

Package integrations provides a central registry for all integration implementations. Integrations can be built-in \(compiled into the binary\) or external \(loaded as plugins\).

Package integrations provides shared utilities for integration implementations.

Index

func ClearCache

func ClearCache()

ClearCache clears all cached instances, forcing reinitialization on next access. Useful for testing or when integrations need to be refreshed.

func Count

func Count() int

Count returns the number of registered integrations.

func Get

func Get(name string) (engine.Integration, error)

Get returns a single integration by name, creating it lazily if needed. This is more efficient than GetAll() when you only need specific integrations.

func GetAll

func GetAll() map[string]engine.Integration

GetAll returns a map of all registered integrations. Uses lazy loading - only creates instances for integrations that haven't been created yet.

func GetLazy

func GetLazy() map[string]func() engine.Integration

GetLazy returns a map of constructors \(not instances\). Use this when you want to defer instantiation until actual use.

func IsDisabled

func IsDisabled(name string) bool

IsDisabled checks if an integration is disabled in the registry.

func IsExperimental

func IsExperimental(name string) bool

IsExperimental checks if an integration is marked as experimental.

func List

func List() []string

List returns a sorted list of all registered integration names.

func ListByCategory

func ListByCategory(category string) (map[string]Metadata, error)

ListByCategory returns integrations grouped by category.

func ListIntegrations

func ListIntegrations() (map[string]Metadata, error)

ListIntegrations returns a list of all integration names with their metadata.

func Register

func Register(name string, constructor func() engine.Integration)

Register adds an integration constructor to the global registry. This is typically called from init() functions in integration packages.

Example:

func init() {
    integrations.Register("npm", New)
}

func ReloadPlugins

func ReloadPlugins() error

ReloadPlugins clears the plugin loaded flag and reloads all plugins. This allows hot-reloading of plugins without restarting the application.

func ValidateFilePath

func ValidateFilePath(path string) error

ValidateFilePath validates that a file path is safe to read/write. It checks for directory traversal attempts to prevent security vulnerabilities.

type CategoryMetadata

CategoryMetadata contains information about an integration category.

type CategoryMetadata struct {
    Name        string `yaml:"name"`
    Description string `yaml:"description"`
}

type DatasourceMetadata

DatasourceMetadata contains information about a datasource.

type DatasourceMetadata struct {
    Name        string `yaml:"name"`
    URL         string `yaml:"url"`
    Type        string `yaml:"type"`
    Description string `yaml:"description"`
}

type Metadata

Metadata contains information about an integration.

type Metadata struct {
    DisplayName  string   `yaml:"displayName"`
    Description  string   `yaml:"description"`
    URL          string   `yaml:"url"`
    Category     string   `yaml:"category"`
    FilePatterns []string `yaml:"filePatterns"`
    Datasources  []string `yaml:"datasources"`
    Experimental bool     `yaml:"experimental"`
    Disabled     bool     `yaml:"disabled"`
}

func GetMetadata

func GetMetadata(name string) (*Metadata, error)

GetMetadata returns metadata for a specific integration.

type RegistryMetadata

RegistryMetadata represents the full integrations.yaml structure.

type RegistryMetadata struct {
    Integrations map[string]Metadata           `yaml:"integrations"`
    Datasources  map[string]DatasourceMetadata `yaml:"datasources"`
    Categories   map[string]CategoryMetadata   `yaml:"categories"`
    Version      string                        `yaml:"version"`
}

func LoadMetadata

func LoadMetadata() (*RegistryMetadata, error)

LoadMetadata loads integration metadata from the integrations.yaml file.

policy

import "github.com/santosr2/uptool/internal/policy"

Package policy handles configuration file parsing and policy management. It defines the structure for uptool.yaml configuration files, including integration-specific policies, update strategies, and organization-level governance settings.

Index

func ValidateIntegrationPolicy

func ValidateIntegrationPolicy(p *engine.IntegrationPolicy) error

ValidateIntegrationPolicy checks that an integration policy is valid.

type AutoMergeConfig

AutoMergeConfig controls automatic PR merging.

type AutoMergeConfig struct {
    Guards  []string `yaml:"guards"`
    Enabled bool     `yaml:"enabled"`
}

type Config

Config represents the uptool.yaml configuration file.

type Config struct {
    OrgPolicy    *OrgPolicy          `yaml:"org_policy,omitempty"`
    Integrations []IntegrationConfig `yaml:"integrations"`
    Version      int                 `yaml:"version"`
}

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a default configuration with sensible defaults.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig reads and parses the configuration file.

func \(\*Config\) EnabledIntegrations

func (c *Config) EnabledIntegrations() []string

EnabledIntegrations returns the IDs of all enabled integrations.

func \(\*Config\) ToPolicyMap

func (c *Config) ToPolicyMap() map[string]engine.IntegrationPolicy

ToPolicyMap converts the configuration into a map of integration policies.

func \(\*Config\) Validate

func (c *Config) Validate() error

Validate checks that the configuration is valid.

type IntegrationConfig

IntegrationConfig defines configuration for a specific integration.

type IntegrationConfig struct {
    Match   *MatchConfig             `yaml:"match,omitempty"`
    ID      string                   `yaml:"id"`
    Policy  engine.IntegrationPolicy `yaml:"policy"`
    Enabled bool                     `yaml:"enabled"`
}

type MatchConfig

MatchConfig specifies file patterns for integration detection.

type MatchConfig struct {
    Files []string `yaml:"files"`
}

type OrgPolicy

OrgPolicy contains organization-level policies and governance settings.

type OrgPolicy struct {
    Signing            *SigningConfig   `yaml:"signing,omitempty"`
    AutoMerge          *AutoMergeConfig `yaml:"auto_merge,omitempty"`
    RequireSignoffFrom []string         `yaml:"require_signoff_from,omitempty"`
}

type SigningConfig

SigningConfig controls artifact signing verification.

type SigningConfig struct {
    CosignVerify bool `yaml:"cosign_verify"`
}

registry

import "github.com/santosr2/uptool/internal/registry"

Package registry provides HTTP clients for querying package registries and release APIs. It includes clients for npm Registry, Terraform Registry, GitHub Releases, and Helm repositories, enabling version lookups and constraint-based version resolution.

Index

func IsOCIRepository

func IsOCIRepository(repository string) bool

IsOCIRepository checks if a repository URL is an OCI registry.

func ParseGitHubURL

func ParseGitHubURL(url string) (owner, repo string, err error)

ParseGitHubURL extracts owner and repo from a GitHub URL. Supports: - https://github.com/owner/repo - github.com/owner/repo - owner/repo

type ChartIndex

ChartIndex represents the index.yaml structure from a Helm repository.

type ChartIndex struct {
    Entries    map[string][]ChartIndexEntry `yaml:"entries"`
    APIVersion string                       `yaml:"apiVersion"`
}

type ChartIndexEntry

ChartIndexEntry represents a single chart version entry.

type ChartIndexEntry struct {
    Created     time.Time `yaml:"created"`
    Name        string    `yaml:"name"`
    Version     string    `yaml:"version"`
    AppVersion  string    `yaml:"appVersion"`
    Description string    `yaml:"description"`
}

type GitHubClient

GitHubClient queries GitHub API for release information.

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

func NewGitHubClient

func NewGitHubClient(token string) *GitHubClient

NewGitHubClient creates a new GitHub API client. Token is optional but recommended to avoid rate limiting.

func \(\*GitHubClient\) FindBestRelease

func (c *GitHubClient) FindBestRelease(ctx context.Context, owner, repo, constraint string, allowPrerelease bool) (string, error)

FindBestRelease finds the best release matching a constraint.

func \(\*GitHubClient\) GetAllReleases

func (c *GitHubClient) GetAllReleases(ctx context.Context, owner, repo string) ([]Release, error)

GetAllReleases fetches all releases for a repository.

func \(\*GitHubClient\) GetLatestRelease

func (c *GitHubClient) GetLatestRelease(ctx context.Context, owner, repo string) (string, error)

GetLatestRelease fetches the latest non-prerelease release for a repository.

type HelmClient

HelmClient queries Helm chart repositories.

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

func NewHelmClient

func NewHelmClient() *HelmClient

NewHelmClient creates a new Helm chart repository client.

func \(\*HelmClient\) FindBestChartVersion

func (c *HelmClient) FindBestChartVersion(ctx context.Context, repository, chartName, constraint string) (string, error)

FindBestChartVersion finds the best chart version matching a constraint.

func \(\*HelmClient\) GetChartVersionDetails

func (c *HelmClient) GetChartVersionDetails(ctx context.Context, repository, chartName string) ([]ChartIndexEntry, error)

GetChartVersionDetails returns all available versions with metadata for a chart from a repository.

func \(\*HelmClient\) GetChartVersions

func (c *HelmClient) GetChartVersions(ctx context.Context, repository, chartName string) ([]string, error)

GetChartVersions returns all available versions for a chart.

func \(\*HelmClient\) GetLatestChartVersion

func (c *HelmClient) GetLatestChartVersion(ctx context.Context, repository, chartName string) (string, error)

GetLatestChartVersion fetches the latest version for a chart from a repository. repository: the base URL of the chart repository \(e.g., "https://charts.bitnami.com/bitnami"\) chartName: the name of the chart \(e.g., "postgresql"\)

type Module

Module represents a module with its versions.

type Module struct {
    Source   string          `json:"source"`
    Versions []ModuleVersion `json:"versions"`
}

type ModuleVersion

ModuleVersion represents a single module version.

type ModuleVersion struct {
    Version string `json:"version"`
}

type ModuleVersions

ModuleVersions represents the response from /v1/modules/{namespace}/{name}/{provider}/versions.

type ModuleVersions struct {
    Modules []Module `json:"modules"`
}

type NPMClient

NPMClient queries the npm registry for package information.

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

func NewNPMClient

func NewNPMClient() *NPMClient

NewNPMClient creates a new npm registry client.

func \(\*NPMClient\) FindBestVersion

func (c *NPMClient) FindBestVersion(ctx context.Context, packageName, constraint string, allowPrerelease bool) (string, error)

FindBestVersion finds the best version matching a constraint.

func \(\*NPMClient\) GetLatestVersion

func (c *NPMClient) GetLatestVersion(ctx context.Context, packageName string) (string, error)

GetLatestVersion fetches the latest version for a package.

func \(\*NPMClient\) GetPackageInfo

func (c *NPMClient) GetPackageInfo(ctx context.Context, packageName string) (*PackageInfo, error)

GetPackageInfo fetches full package information from npm registry.

func \(\*NPMClient\) GetVersions

func (c *NPMClient) GetVersions(ctx context.Context, packageName string) ([]string, error)

GetVersions returns all available versions for a package.

type PackageInfo

PackageInfo contains npm package metadata.

type PackageInfo struct {
    Versions map[string]map[string]interface{} `json:"versions"`
    DistTags map[string]string                 `json:"dist-tags"`
    Time     map[string]string                 `json:"time"`
    Name     string                            `json:"name"`
}

type ProviderVersion

ProviderVersion represents a single provider version.

type ProviderVersion struct {
    Version   string   `json:"version"`
    Platforms []string `json:"platforms"`
}

type ProviderVersions

ProviderVersions represents the response from /v1/providers/{namespace}/{type}/versions.

type ProviderVersions struct {
    Versions []ProviderVersion `json:"versions"`
}

type Release

Release represents a GitHub release.

type Release struct {
    TagName     string `json:"tag_name"`
    Name        string `json:"name"`
    CreatedAt   string `json:"created_at"`
    PublishedAt string `json:"published_at"`
    Draft       bool   `json:"draft"`
    Prerelease  bool   `json:"prerelease"`
}

type TerraformClient

TerraformClient queries the Terraform Registry API.

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

func NewTerraformClient

func NewTerraformClient() *TerraformClient

NewTerraformClient creates a new Terraform Registry client.

func \(\*TerraformClient\) FindBestProviderVersion

func (c *TerraformClient) FindBestProviderVersion(ctx context.Context, source, constraint string) (string, error)

FindBestProviderVersion finds the best provider version matching a constraint.

func \(\*TerraformClient\) GetLatestModuleVersion

func (c *TerraformClient) GetLatestModuleVersion(ctx context.Context, source string) (string, error)

GetLatestModuleVersion fetches the latest version for a module. source format: "namespace/name/provider" \(e.g., "terraform\-aws\-modules/vpc/aws"\)

func \(\*TerraformClient\) GetLatestProviderVersion

func (c *TerraformClient) GetLatestProviderVersion(ctx context.Context, source string) (string, error)

GetLatestProviderVersion fetches the latest version for a provider. source format: "namespace/name" \(e.g., "hashicorp/aws"\)

func \(\*TerraformClient\) GetModuleVersions

func (c *TerraformClient) GetModuleVersions(ctx context.Context, source string) ([]ModuleVersion, error)

GetModuleVersions returns all available versions for a module. source format: "namespace/name/provider" \(e.g., "terraform\-aws\-modules/vpc/aws"\)

resolve

import "github.com/santosr2/uptool/internal/resolve"

Package resolve provides semantic version resolution and selection logic. It implements version constraint checking, policy-based version selection, and semantic version impact calculation \(patch/minor/major\).

Index

func CompareVersions

func CompareVersions(v1, v2 string) (int, error)

CompareVersions returns -1 if v1 \< v2, 0 if v1 == v2, 1 if v1 > v2.

func IsValidSemver

func IsValidSemver(version string) bool

IsValidSemver checks if a string is a valid semver version.

func SelectVersion

func SelectVersion(currentVersion string, availableVersions []string, policy engine.IntegrationPolicy) (string, engine.Impact, error)

SelectVersion chooses the best version from a list based on policy. It filters versions by update strategy and prerelease policy, then returns the latest.

rewrite

import "github.com/santosr2/uptool/internal/rewrite"

Package rewrite provides utilities for rewriting structured files while preserving formatting. It includes functions for YAML manipulation, unified diff generation, and patch creation, enabling integrations to update configuration files without destroying formatting or comments.

Index

func CountChanges

func CountChanges(diff string) (additions, deletions int)

CountChanges returns the number of additions and deletions in a diff.

func GeneratePatch

func GeneratePatch(filename, oldContent, newContent string) (string, error)

GeneratePatch creates a git-style patch with timestamps.

func GenerateUnifiedDiff

func GenerateUnifiedDiff(filename, oldContent, newContent string) (string, error)

GenerateUnifiedDiff creates a unified diff between old and new content.

func ReplaceYAMLValue

func ReplaceYAMLValue(content string, path []string, oldValue, newValue string, matcher func(*yaml.Node) bool) (string, error)

ReplaceYAMLValue replaces a specific value in a YAML document while preserving formatting. path specifies the location \(e.g., \["repos", "\*", "rev"\]\) where * matches any element. matcher is an optional function to further filter which nodes to update.

func UpdateYAMLField

func UpdateYAMLField(content string, path []string, newValue string) (string, error)

UpdateYAMLField updates a specific field in a YAML document.

secureio

import "github.com/santosr2/uptool/internal/secureio"

Package secureio provides secure file I/O operations with path validation.

Index

func Create

func Create(path string) (*os.File, error)

Create safely creates a file after validating the path

func ReadFile

func ReadFile(path string) ([]byte, error)

ReadFile safely reads a file after validating the path

func ValidateFilePath

func ValidateFilePath(path string) error

ValidateFilePath validates that a file path is safe to read/write

func WriteFile

func WriteFile(path string, data []byte, perm os.FileMode) error

WriteFile safely writes a file after validating the path

version

import "github.com/santosr2/uptool/internal/version"

Package version provides version information for uptool. The version is embedded from the VERSION file at the repository root.

Index

func Get

func Get() string

Get returns the current uptool version.

cmd

import "github.com/santosr2/uptool/cmd/uptool/cmd"

Package cmd implements the command-line interface for uptool. It provides commands for scanning, planning, and updating dependency manifests across multiple ecosystems \(npm, Helm, Terraform, pre\-commit, asdf, mise, tflint\).

The CLI is built using Cobra and provides the following commands:

  • scan: Discover all manifests in a repository
  • plan: Generate an update plan showing available dependency updates
  • update: Apply updates to manifest files
  • list: List all supported integrations and their status
  • completion: Generate shell completion scripts

Global flags available across all commands:

  • -v, --verbose: Enable verbose debug output
  • -q, --quiet: Suppress informational output \(errors only\)

Example usage:

# Scan repository for manifests
uptool scan

# Generate update plan
uptool plan

# Apply updates (dry-run first)
uptool update --dry-run --diff
uptool update

# Update only specific integrations
uptool update --only=npm,helm

See individual command documentation for detailed usage and options.

Index

func Execute

func Execute() error

Execute runs the root command

func GetLogLevel

func GetLogLevel() slog.Level

GetLogLevel returns the current log level based on flags

python

import "github.com/santosr2/uptool/examples/plugins/python"

Package main implements an uptool plugin for Python requirements.txt dependencies. This plugin demonstrates the external plugin architecture for uptool.

Index

func New

func New() engine.Integration

New creates a new Python integration instance.

func ParseRequirements

func ParseRequirements(content string) ([]*engine.Dependency, error)

ParseRequirements parses a requirements.txt file and extracts dependencies. It handles: - Simple version pins \(package==1.0.0\) - Version constraints \(package\>=1.0.0\) - Comments \(\# comment\) - Blank lines - Extras \(package\[extra\]==1.0.0\)

func RegisterWith

func RegisterWith(register func(name string, constructor func() engine.Integration))

RegisterWith is called by uptool to register this plugin's integrations. This function MUST be exported and have this exact signature for the plugin to work.

uptool will call this function and pass its Register function, which the plugin should call to register each integration it provides.

type Integration

Integration implements the engine.Integration interface for Python requirements.txt.

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

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply executes the update plan by rewriting requirements.txt.

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect finds requirements.txt files in the repository.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan generates an update plan for a requirements.txt file.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate checks if a requirements.txt file is valid.

type PyPIClient

PyPIClient queries the PyPI JSON API for package information.

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

func NewPyPIClient

func NewPyPIClient() *PyPIClient

NewPyPIClient creates a new PyPI client.

func \(\*PyPIClient\) GetLatestVersion

func (c *PyPIClient) GetLatestVersion(ctx context.Context, packageName string) (string, error)

GetLatestVersion fetches the latest stable version for a package from PyPI.

type PyPIResponse

PyPIResponse represents the PyPI JSON API response.

type PyPIResponse struct {
    Info struct {
        Name    string `json:"name"`
        Version string `json:"version"`
    }   `json:"info"`
    Releases map[string][]struct {
        Yanked bool `json:"yanked"`
    }   `json:"releases"`
}

all

import "github.com/santosr2/uptool/internal/integrations/all"

Package all imports all integration packages to trigger their self-registration. Import this package with a blank identifier to enable all integrations:

import _ "github.com/santosr2/uptool/internal/integrations/all"

Index

asdf

import "github.com/santosr2/uptool/internal/integrations/asdf"

Package asdf provides integration for asdf tool version manager. It detects and updates .tool-versions files.

Status: EXPERIMENTAL - Version resolution not yet implemented

Index

type Integration

Integration implements the engine.Integration interface for asdf.

type Integration struct{}

func New

func New() *Integration

New creates a new asdf integration.

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply applies updates to asdf manifest files.

Note: Apply is not implemented for asdf. Use native asdf commands instead:

  • asdf plugin update --all # Update all plugins
  • asdf install \<tool> latest # Install latest version of a tool

To manually update versions in .tool-versions:

  1. Check available versions: asdf list all \<tool>
  2. Edit .tool-versions with desired versions
  3. Install: asdf install

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect scans for .tool-versions files.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan generates an update plan for asdf tools.

Note: asdf integration is experimental. Version resolution is not implemented because each tool \(.tool\-versions can contain nodejs, python, ruby, terraform, etc.\) has its own registry and update mechanism. This would require datasources for every possible runtime.

Recommended approach: Use native asdf commands:

  • asdf plugin update --all # Update plugin versions
  • asdf latest --all # Show latest versions
  • asdf install \<tool> latest # Install latest version

Future enhancement: Could implement version checking via tool-specific datasources \(npm registry, python.org, ruby gems, etc.\) or by calling asdf native commands.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate validates an asdf manifest.

helm

import "github.com/santosr2/uptool/internal/integrations/helm"

Package helm implements the Helm chart integration for updating Chart.yaml dependencies. It detects Chart.yaml files, queries Helm chart repositories for version updates, and rewrites chart dependency versions while preserving YAML structure.

Index

type Chart

Chart represents the structure of Chart.yaml.

type Chart struct {
    Raw          map[string]any `yaml:",inline"`
    APIVersion   string         `yaml:"apiVersion"`
    Name         string         `yaml:"name"`
    Description  string         `yaml:"description"`
    Type         string         `yaml:"type"`
    Version      string         `yaml:"version"`
    AppVersion   string         `yaml:"appVersion"`
    Dependencies []Dependency   `yaml:"dependencies,omitempty"`
}

type Dependency

Dependency represents a chart dependency.

type Dependency struct {
    Name       string `yaml:"name"`
    Version    string `yaml:"version"`
    Repository string `yaml:"repository"`
    Condition  string `yaml:"condition,omitempty"`
    Tags       string `yaml:"tags,omitempty"`
    Alias      string `yaml:"alias,omitempty"`
    Enabled    bool   `yaml:"enabled,omitempty"`
}

type Integration

Integration implements helm chart updates.

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

func New

func New() *Integration

New creates a new helm integration.

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply executes the update by rewriting Chart.yaml.

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect finds Chart.yaml files in the repository.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan determines available updates for helm chart dependencies.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate checks if the Chart.yaml is valid.

mise

import "github.com/santosr2/uptool/internal/integrations/mise"

Package mise provides integration for mise tool version manager. It detects and updates mise.toml, .mise.toml, and optionally .tool-versions files. mise is backward-compatible with asdf's .tool-versions format.

Status: EXPERIMENTAL - Version resolution not yet implemented

Index

type Config

Config represents the structure of a mise.toml file.

type Config struct {
    Tools map[string]interface{} `toml:"tools"`
}

type Integration

Integration implements the engine.Integration interface for mise.

type Integration struct{}

func New

func New() *Integration

New creates a new mise integration.

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply applies updates to mise manifest files.

Note: Apply is not implemented for mise. Use native mise commands instead:

  • mise upgrade # Upgrade all tools to latest
  • mise use \<tool>@latest # Pin specific tool to latest

To manually update versions in mise.toml or .mise.toml:

  1. Check available versions: mise ls-remote \<tool>
  2. Edit mise.toml with desired versions
  3. Install: mise install

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect scans for mise.toml and .mise.toml files.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan generates an update plan for mise tools.

Note: mise integration is experimental. Version resolution is not implemented because each tool \(mise.toml can contain nodejs, python, ruby, terraform, etc.\) has its own registry and update mechanism. This would require datasources for every possible runtime.

Recommended approach: Use native mise commands:

  • mise upgrade # Upgrade all tools to latest versions
  • mise outdated # Show outdated tools
  • mise use \<tool>@latest # Pin to latest version

Future enhancement: Could implement version checking via tool-specific datasources \(npm registry, python.org, ruby gems, etc.\) or by calling mise native commands.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate validates a mise manifest.

npm

import "github.com/santosr2/uptool/internal/integrations/npm"

Package npm implements the npm integration for updating package.json dependencies. It detects package.json files, queries the npm registry for version updates, and rewrites dependency versions while preserving constraint prefixes \(^, \~, \>=\).

Index

type Integration

Integration implements npm package.json updates.

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

func New

func New() *Integration

New creates a new npm integration.

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply executes the update plan by rewriting package.json.

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect finds package.json files in the repository.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan determines available updates for npm dependencies.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate runs npm validation \(optional\).

type PackageJSON

PackageJSON represents the structure of package.json.

type PackageJSON struct {
    Dependencies         map[string]string `json:"dependencies,omitempty"`
    DevDependencies      map[string]string `json:"devDependencies,omitempty"`
    PeerDependencies     map[string]string `json:"peerDependencies,omitempty"`
    OptionalDependencies map[string]string `json:"optionalDependencies,omitempty"`
    Name                 string            `json:"name,omitempty"`
    Version              string            `json:"version,omitempty"`
}

precommit

import "github.com/santosr2/uptool/internal/integrations/precommit"

Package precommit implements the pre-commit integration using the native autoupdate command. It detects .pre-commit-config.yaml files, runs 'pre-commit autoupdate' to update hook versions, and parses the output to report changes. This follows the manifest-first philosophy by using the native tool that directly updates the configuration file.

Index

type Config

Config represents the structure of .pre-commit-config.yaml.

type Config struct {
    Repos []Repo `yaml:"repos"`
}

type Hook

Hook represents a pre-commit hook.

type Hook struct {
    ID string `yaml:"id"`
}

type Integration

Integration implements pre-commit hook updates using native autoupdate command.

type Integration struct{}

func New

func New() *Integration

New creates a new pre-commit integration.

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply executes the update using native pre-commit autoupdate command.

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect finds .pre-commit-config.yaml files in the repository.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan determines available updates for pre-commit hooks. For pre-commit, we use the native autoupdate command in dry-run mode.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate runs pre-commit validate-config.

type Repo

Repo represents a pre-commit repository.

type Repo struct {
    Repo  string `yaml:"repo"`
    Rev   string `yaml:"rev"`
    Hooks []Hook `yaml:"hooks,omitempty"`
}

terraform

import "github.com/santosr2/uptool/internal/integrations/terraform"

Package terraform implements the Terraform integration for updating module versions in .tf files. It detects Terraform configuration files, parses HCL to extract module and provider versions, queries the Terraform Registry for updates, and rewrites versions while preserving HCL formatting.

Index

type Block

Block represents a terraform configuration block.

type Block struct {
    Remain            hcl.Body                `hcl:",remain"`
    RequiredProviders *RequiredProvidersBlock `hcl:"required_providers,block"`
    RequiredVersion   string                  `hcl:"required_version,optional"`
}

type Config

Config represents terraform configuration structure.

type Config struct {
    Remain    hcl.Body        `hcl:",remain"`
    Terraform []Block         `hcl:"terraform,block"`
    Modules   []ModuleBlock   `hcl:"module,block"`
    Providers []ProviderBlock `hcl:"provider,block"`
}

type Integration

Integration implements terraform configuration updates.

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

func New

func New() *Integration

New creates a new terraform integration.

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply executes the update by rewriting terraform files.

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect finds .tf files in the repository.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan determines available updates for terraform providers and modules.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate checks if the terraform configuration is valid.

type ModuleBlock

ModuleBlock represents a module block.

type ModuleBlock struct {
    Remain  hcl.Body `hcl:",remain"`
    Name    string   `hcl:"name,label"`
    Source  string   `hcl:"source,optional"`
    Version string   `hcl:"version,optional"`
}

type ProviderBlock

ProviderBlock represents a provider block.

type ProviderBlock struct {
    Remain hcl.Body `hcl:",remain"`
    Name   string   `hcl:"name,label"`
}

type RequiredProvidersBlock

RequiredProvidersBlock represents the required_providers block.

type RequiredProvidersBlock struct {
    Body hcl.Body `hcl:",remain"`
}

tflint

import "github.com/santosr2/uptool/internal/integrations/tflint"

Package tflint implements the tflint integration for updating plugin versions in .tflint.hcl files. It detects tflint configuration files, parses HCL to extract plugin versions, queries GitHub Releases for plugin updates, and rewrites versions while preserving HCL formatting.

Index

type Config

Config represents .tflint.hcl structure.

type Config struct {
    Remain  hcl.Body `hcl:",remain"`
    Plugins []Plugin `hcl:"plugin,block"`
    Rules   []Rule   `hcl:"rule,block"`
}

type Integration

Integration implements tflint configuration updates.

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

func New

func New() *Integration

New creates a new tflint integration.

func \(\*Integration\) Apply

func (i *Integration) Apply(ctx context.Context, plan *engine.UpdatePlan) (*engine.ApplyResult, error)

Apply executes the update by rewriting the HCL file.

func \(\*Integration\) Detect

func (i *Integration) Detect(ctx context.Context, repoRoot string) ([]*engine.Manifest, error)

Detect finds .tflint.hcl files in the repository.

func \(\*Integration\) Name

func (i *Integration) Name() string

Name returns the integration identifier.

func \(\*Integration\) Plan

func (i *Integration) Plan(ctx context.Context, manifest *engine.Manifest) (*engine.UpdatePlan, error)

Plan determines available updates for tflint plugins.

func \(\*Integration\) Validate

func (i *Integration) Validate(ctx context.Context, manifest *engine.Manifest) error

Validate checks if the HCL file is valid.

type Plugin

Plugin represents a tflint plugin block.

type Plugin struct {
    Remain  hcl.Body `hcl:",remain"`
    Name    string   `hcl:"name,label"`
    Version string   `hcl:"version,optional"`
    Source  string   `hcl:"source,optional"`
    Enabled bool     `hcl:"enabled,optional"`
}

type Rule

Rule represents a tflint rule block.

type Rule struct {
    Remain  hcl.Body `hcl:",remain"`
    Name    string   `hcl:"name,label"`
    Enabled bool     `hcl:"enabled,optional"`
}

Generated by gomarkdoc