cmd

package
v0.1.13 Latest Latest
Warning

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

 Go to latest Published: Sep 30, 2025 License: Apache-2.0 Imports: 23 Imported by: 1

Documentation

Overview

Package cmd implements the core functionality of locksmith - the renv.lock generator.

Package cmd implements the core functionality of locksmith - the renv.lock generator.

Index

Constants

View Source 
const GitHub = "GitHub"
View Source 
const GitLab = "GitLab"

Variables

This section is empty.

Functions

func CheckIfBasePackage 

func CheckIfBasePackage(name string) bool

CheckIfBasePackage checks whether the package should be treated as a base R package (included in every R installation) or if it should be treated as a dependency to be downloaded from a package repository.

func CheckIfSkipDependency 

func CheckIfSkipDependency(indentation string, packageName string, dependencyName string,
	versionOperator string, versionValue string, outputList *[]PackageDescription,
	dependencyChain string) bool

CheckIfSkipDependency checks if processing of the package (dependency) should be skipped. Dependency should be skipped if it is a base R package, or has already been added to output package list (later used to generate the renv.lock).

func CheckIfVersionSufficient 

func CheckIfVersionSufficient(availableVersionValue string, versionOperator string,
	requiredVersionValue string) bool

CheckIfVersionSufficient checks if availableVersionValue fulfills the requirement expressed by versionOperator ('>=' or '>') and requiredVersionValue.

func CleanDescriptionOrPackagesEntry 

func CleanDescriptionOrPackagesEntry(description string, isDescription bool) string

CleanDescriptionOrPackagesEntry processes a multiline string representing information about one package from PACKAGES file (if isDescription is false), or the whole contents of DESCRIPTION file (if isDescription is true). Removes newlines occurring within filtered fields (which are predominantly fields containing lists of package dependencies). Also removes fields which are not required for further processing.

func DownloadPackagesFiles 

func DownloadPackagesFiles(repositoryList []string,
	downloadFileFunction func(string, map[string]string) (int64, string, error)) map[string]string

DownloadPackagesFiles downloads PACKAGES files from repository URLs specified in the repositoryList. Returns a map from repository URL to the string with the contents of PACKAGES file for that repository.

func DownloadTextFile 

func DownloadTextFile(url string, parameters map[string]string) (int64, string, error)

DownloadTextFile returns number of bytes in downloaded content, the downloaded content itself as a string, and error if any occurred.

func Execute 

func Execute()

func GenerateHTMLReport added in v0.1.11 

func GenerateHTMLReport(outputPackageList []PackageDescription,
	inputPackageDescriptions []PackageDescription, packagesFiles map[string]PackagesFile,
	renvLockContents RenvLock, repositoryMap map[string]string)

func GetDefaultBranchSha added in v0.1.4 

func GetDefaultBranchSha(gitDirectory string, repoURL string,
	environmentCredentialsType string) (string, string)

GetDefaultBranchSha clones the git repository located at repoURL to gitDirectory, using Personal Access Tokens from LOCKSMITH_GITLABTOKEN or LOCKSMITH_GITHUBTOKEN environment variables. It returns the commit SHA of the HEAD of default branch and the name of the default branch, or empty string in case of error.

func GetGitHubSha 

func GetGitHubSha(remoteUsername string, remoteRepo string, remoteRef string, token map[string]string,
	downloadFileFunction func(string, map[string]string) (int64, string, error)) string

GetGitHubSha retrieves SHA of the remoteRef from the remoteUsername/remoteRepo GitHub repository.

func GetGitLabProjectAndSha 

func GetGitLabProjectAndSha(projectURL string, remoteRef string, token map[string]string,
	downloadFileFunction func(string, map[string]string) (int64, string, error)) (string, string, string)

GetGitLabProjectAndSha retrieves information about GitLab repository (project path, repository name and commit SHA) from projectURL GitLab API endpoint.

func GetGitRepositoryURL added in v0.1.4 

func GetGitRepositoryURL(p PackageDescription) string

GetGitRepositoryURL reads the PackageDescription struct corresponding to a single package in the renv.lock and returns the git repository URL from which the package should be cloned.

func GetLatestPackageVersionFromAnyRepository added in v0.1.6 

func GetLatestPackageVersionFromAnyRepository(soughtPackageName string, packagesFiles map[string]PackagesFile) string

GetLatestPackageVersionFromAnyRepository searches for the latest version of soughtPackageName in packagesFiles. It returns the name of the repository (as defined in renv.lock header) where the latest version of that package has been found.

func GetPackageRegex added in v0.1.4 

func GetPackageRegex(updatedPackages string) string

GetPackageRegex processes the comma-separated expression with wildcards indicating which packages should be updated and returns a real regex.

func GetPackageVersionFromDescription added in v0.1.4 

func GetPackageVersionFromDescription(descriptionFilePath string) string

GetPackageVersionFromDescription reads the DESCRIPTION file located in descriptionFilePath and returns the package version.

func GetPackagesFileContent added in v0.1.4 

func GetPackagesFileContent(repositoryURL string,
	downloadFileFunction func(string, map[string]string) (int64, string, error)) string

GetPackagesFileContent downloads the PACKAGES file from the repositoryURL using the downloadFileFunction and returns the contents, or empty string in case of error.

func GetPackagesFiles added in v0.1.4 

func GetPackagesFiles(renvLock RenvLock) map[string]PackagesFile

GetPackagesFiles downloads PACKAGES files from repositories defined in the renv.lock header. It returns a map from the repository name (as defined in the renv.lock header) to the PackagesFile struct representing repository's PACKAGES file.

func GetRepositoryKeyByValue 

func GetRepositoryKeyByValue(repositoryURL string, repositoryMap map[string]string) string

GetRepositoryKeyByValue searches for repository URL in repositoryMap and returns the name (alias) of that repository which will then be used in output renv.lock file.

func ParseInput 

func ParseInput() ([]string, []string, map[string]string, []string)

ParseInput parses CLI input parameters, and returns: list of package DESCRIPTION URLs, list of package repository URLs (in descending priority order), a map from package repository alias (name) to the package repository URL, and a list of allowed types of missing dependencies.

func ParsePackagesFiles 

func ParsePackagesFiles(repositoryPackageFiles map[string]string) map[string]PackagesFile

ParsePackagesFiles iterates through package repository PACKAGES files.

func ProcessDependencyFields 

func ProcessDependencyFields(packageMap map[string]string,
	packageDependencies *[]Dependency)

ProcessDependencyFields processes a map containing a YAML-like object representing dependencies of a package. Returns a list of Dependency structures corresponding to dependency name, and version constraints.

func ProcessDescription 

func ProcessDescription(description DescriptionFile, allPackages *[]PackageDescription)

ProcessDescription reads a string containing DESCRIPTION file and returns a structure with those fields/properties that are required for further processing.

func ProcessDescriptionURL 

func ProcessDescriptionURL(descriptionURL string,
	downloadFileFunction func(string, map[string]string) (int64, string, error),
) (map[string]string, string, string, string, string, string, string, string, string)

ProcessDescriptionURL gets information about the git repository in which the package is stored based on the provided descriptionURL to the package DESCRIPTION file.

func ProcessMissingPackage added in v0.1.3 

func ProcessMissingPackage(indentation string, packageName string, versionOperator string,
	versionValue string, dependencyType string, allowedMissingDependencyTypes []string,
	fatalMissingPackageVersions map[string]DependencyVersion,
	nonFatalMissingPackageVersions map[string]DependencyVersion,
	dependencyChain string)

ProcessMissingPackage saves information about missing packages (dependencies) and their versions. This information is later reported to the user, together with optionally exiting the application with failed status, depending on the types of missing dependencies and the configuration provided by --allowIncompleteRenvLock flag.

func ResolveDependenciesRecursively 

func ResolveDependenciesRecursively(outputList *[]PackageDescription, name string, versionOperator string,
	versionValue string, dependencyType string, allowedMissingDependencyTypes []string,
	repositoryList []string, packagesFiles map[string]PackagesFile, recursionLevel int,
	fatalMissingPackageVersions map[string]DependencyVersion,
	nonFatalMissingPackageVersions map[string]DependencyVersion,
	dependencyChain string)

ResolveDependenciesRecursively checks dependencies of the package, and their required versions. Checks if the required version is already included in the output package list (later used to generate the renv.lock), or if the dependency should be downloaded from a package repository. Repeats the process recursively for all dependencies not yet processed.

func UpdateGitPackages added in v0.1.4 

func UpdateGitPackages(renvLock *RenvLock, updatePackageRegexp string,
	getDefaultBranchShaFunction func(string, string, string) (string, string),
	gitUpdatesDirectory string)

UpdateGitPackages iterates through the packages in renv.lock and updates the entries corresponding to packages stored in git repositories. Package version and latest commit SHA are updated in the renvLock struct. Only packages matching the updatePackageRegexp are updated.

func UpdateRepositoryPackages added in v0.1.4 

func UpdateRepositoryPackages(renvLock *RenvLock, updatePackageRegexp string,
	packagesFiles map[string]PackagesFile)

UpdateRepositoryPackages iterates through the packages in renv.lock and updates the entries corresponding to packages downloaded from CRAN-like repositories. Package version is updated in the renvLock struct. Only packages matching the updatePackageRegexp are updated.

Types

type Dependency 

type Dependency struct {
	DependencyType  string `json:"type"`
	DependencyName  string `json:"name"`
	VersionOperator string `json:"operator"`
	VersionValue    string `json:"value"`
}

type DependencyVersion added in v0.1.3 

type DependencyVersion struct {
	VersionOperator string `json:"operator"`
	VersionValue    string `json:"value"`
}

type DescriptionFile 

type DescriptionFile struct {
	// Contents stores the DESCRIPTION file.
	Contents string `json:"contents"`
	// PackageSource can be either 'GitHub' or 'GitLab'.
	PackageSource string `json:"source"`
	// RemoteType can be either 'github' or 'gitlab'.
	RemoteType string `json:"remoteType"`
	// RemoteHost can be 'api.github.com' or the URL of GitLab instance,
	// for example: 'https://gitlab.example.com'.
	RemoteHost string `json:"remoteHost"`
	// RemoteUsername represents the organization or the owner in case of a GitHub
	// repository, or the path to the repository in the project tree in case of
	// a GitLab repository.
	RemoteUsername string `json:"remoteUsername"`
	// RemoteRepo contains the name of git repository.
	RemoteRepo string `json:"remoteRepo"`
	// RemoteSubdir is an optional field storing the path to the package inside
	// the git repository in case the package is not located in the root of the
	// git repository.
	RemoteSubdir string `json:"remoteSubdir"`
	// RemoteRef is tag or branch name representing the verion of the provided
	// package DESCRIPTION file. If RemoteRef matches `v\d+(\.\d+)*` regex,
	// it is treated as a git tag, otherwise it is treated as a git branch.
	RemoteRef string `json:"remoteRef"`
	// RemoteSha is the commit SHA for the RemoteRef.
	RemoteSha string `json:"remoteSha"`
}

DescriptionFile represents the input package DESCRIPTION file together with related information about the git repository where the package is stored. This structure represents data about input git packages before it is parsed into a PackageDescription struct.

func DownloadDescriptionFiles 

func DownloadDescriptionFiles(packageDescriptionList []string,
	downloadFileFunction func(string, map[string]string) (int64, string, error)) []DescriptionFile

DownloadDescriptionFiles downloads DESCRIPTION files from packageDescriptionList. It returns a list of structures representing: the contents of DESCRIPTION file for the packages and various information about git repositories storing the packages.

type ErrorCaptureHook added in v0.1.11 

type ErrorCaptureHook struct {
	ErrorEntries *bytes.Buffer
}

func (*ErrorCaptureHook) Fire added in v0.1.11 

func (hook *ErrorCaptureHook) Fire(entry *logrus.Entry) error

func (*ErrorCaptureHook) Levels added in v0.1.11 

func (hook *ErrorCaptureHook) Levels() []logrus.Level

type GitHubObject 

type GitHubObject struct {
	Sha string `json:"sha"`
}

type GitHubTagOrBranchResponse 

type GitHubTagOrBranchResponse struct {
	Object GitHubObject `json:"object"`
}

type GitLabAPIResponse 

type GitLabAPIResponse struct {
	PathWithNamespace string `json:"path_with_namespace"`
}

type GitLabCommit 

type GitLabCommit struct {
	ID string `json:"id"`
}

type GitLabTagOrBranchResponse 

type GitLabTagOrBranchResponse struct {
	Commit GitLabCommit `json:"commit"`
}

type HTMLReport added in v0.1.11 

type HTMLReport struct {
	Config []HTMLReportConfigItem
	// Errors will be written to the report only if locksmith
	// is running with logLevel = error or lower.
	Errors string
	// Errors will be written to the report only if locksmith
	// is running with logLevel = warning or lower.
	Warnings         string
	Dependencies     []HTMLReportDependency
	RenvLockContents string
}

type HTMLReportConfigItem added in v0.1.11 

type HTMLReportConfigItem struct {
	Key   string
	Value string
}

type HTMLReportDependency added in v0.1.11 

type HTMLReportDependency struct {
	Name       string
	Version    string
	Repository string
	Depends    string
	Imports    string
	LinkingTo  string
	Suggests   string
}

type PackageDescription 

type PackageDescription struct {
	// Package stores the package name.
	Package string `json:"Package"`
	// Version stores the package version.
	Version string `json:"Version"`
	// Source can be one of: 'GitHub', 'GitLab' (for packages from git repositories)
	// or 'Repository' (for packages from package repositories).
	Source string `json:"Source"`
	// Repository stores the URL or the name (depending on the stage of processing)
	// of the package repository, in case Source is 'Repository'.
	Repository string `json:"Repository,omitempty"`
	// Dependencies contains the list of package dependencies.
	Dependencies []Dependency `json:"Dependencies,omitempty"`
	// When processing packages stored in package repositories, the Remote* fields below are empty.
	// These fields are documented in the DescriptionFile struct.
	RemoteType     string `json:"RemoteType,omitempty"`
	RemoteHost     string `json:"RemoteHost,omitempty"`
	RemoteUsername string `json:"RemoteUsername,omitempty"`
	RemoteRepo     string `json:"RemoteRepo,omitempty"`
	RemoteSubdir   string `json:"RemoteSubdir,omitempty"`
	RemoteRef      string `json:"RemoteRef,omitempty"`
	RemoteSha      string `json:"RemoteSha,omitempty"`
	// Requirements field is not used, except to be able to unmarshal renv.lock JSON in which
	// this field is present.
	Requirements []string `json:"Requirements,omitempty"`
	Hash         string   `json:"Hash,omitempty"`
}

PackageDescription represents an R package.

func ConstructOutputPackageList 

func ConstructOutputPackageList(packages []PackageDescription, packagesFiles map[string]PackagesFile,
	repositoryList []string, allowedMissingDependencyTypes []string) []PackageDescription

ConstructOutputPackageList generates a list of all packages and their dependencies which should be included in the output renv.lock file, based on the list of package descriptions, and information contained in the PACKAGES files.

func ParseDescriptionFileList 

func ParseDescriptionFileList(inputDescriptionFiles []DescriptionFile) []PackageDescription

ParseDescriptionFileList iterates through package DESCRIPTION files.

type PackagesFile 

type PackagesFile struct {
	Packages []PackageDescription `json:"packages"`
}

func ProcessPackagesFile 

func ProcessPackagesFile(content string) PackagesFile

ProcessPackagesFile reads a string containing PACKAGES file, and returns a structure with those fields/properties that are required for further processing.

type RenvLock 

type RenvLock struct {
	R        RenvLockContents              `json:"R"`
	Packages map[string]PackageDescription `json:"Packages"`
}

func GenerateRenvLock 

func GenerateRenvLock(packageList []PackageDescription, repositoryMap map[string]string) RenvLock

GenerateRenvLock generates renv.lock file structure which can be then saved as a JSON file. It uses a list of package data created by ConstructOutputPackageList, and the map of package repositories containing the packages.

func UpdateRenvLock added in v0.1.4 

func UpdateRenvLock(inputFileName, updatePackages string) RenvLock

UpdateRenvLock reads the renv.lock from inputFileName. It then retrieves the information about the newest package versions from respective repositories (CRAN-like or git repositories) from which the packages should be downloaded according to the renv.lock. It returns the RenvLock struct represeting the renv.lock with updated package versions.

type RenvLockContents 

type RenvLockContents struct {
	Repositories []RenvLockRepository `json:"Repositories"`
}

type RenvLockRepository 

type RenvLockRepository struct {
	Name string `json:"Name"`
	URL  string `json:"URL"`
}

type WarningCaptureHook added in v0.1.11 

type WarningCaptureHook struct {
	WarnEntries *bytes.Buffer
}

func (*WarningCaptureHook) Fire added in v0.1.11 

func (hook *WarningCaptureHook) Fire(entry *logrus.Entry) error

func (*WarningCaptureHook) Levels added in v0.1.11 

func (hook *WarningCaptureHook) Levels() []logrus.Level

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.