Write short scripts in a simple DSL and use the prospectus tool to check for changes in expected vs. actual state.
I use this for checking my homebrew tap and ArchLinux packages for outdated package versions: it compares the version I'm packaging now against the upstream latest version.
This gem reads a "./.prospectus" file to determine expected/actual state. A prospectus file can be pretty lightweight:
item do
name 'zlib'
expected do
github_release
repo 'madler/zlib'
regex /^v(.*)$/
end
actual do
git_tag
regex /^(.*)-\d+$/
end
end
Prospectus works by letting you define "items", each of which have an "expected" and "actual" block. You can specify a "name", as above, otherwise it will infer the name from the directory containing the prospectus file.
The expected/actual blocks first define the module to be used, and then define any configuration for that module.
To run the check, just run prospectus
in the directory with the .prospectus file, or use prospectus -d /path/to/directory
.
If you're looking to parse the output with something else, consider using -j to get JSON output.
The following modules are included with Prospectus.
Most of the examples below will use either an expected or actual block, based on the most common use case, but any module can be used for either state.
This checks the git tag of the local repo. Supports the Regex helper
# This would use the current git tag directly
actual do
git_tag
end
# This would convert v1.0.0 into 1.0.0
actual do
git_tag
regex /^v([\d.]+)$/
end
# And this would convert v1_0_0 into 1.0.0
actual do
git_tag
regex /^v(\d+)_(\d+)_(\d+)$/, '\1.\2.\3'
end
Checks the git hash of a local repository. Supports the chdir helper.
Will return the short hash unless the long
argument is provided.
Primarily used for checking git submodules.
# Returns the short hash
actual do
git_hash
dir 'submodules/my-important-other-repo'
end
# Returns the full hash
actual do
git_hash
long
dir 'submodules/other-repo'
end
This checks the latest GitHub release for a repo (must be a real Release, not just a tag. Use github_tag if there isn't a Release). Supports the Regex and Filter helpers and uses the GitHub API helper for API access. To track prerelease
Releases, use allow_prerelease
expected do
github_release
repo 'amylum/s6'
end
This checks the latest GitHub tag for a repo. Supports the Regex and Filter helpers and uses the GitHub API helper for API access.
expected do
github_tag
repo 'reubenhwk/radvd'
end
This checks the latest commit hash on GitHub. Uses the github_api helper, which requires octoauth. Designed to be used alongside the git_hash module for comparing local submodules with upstream commits.
Will give the 7 character short hash unless "long" is specified.
expected do
github_hash
repo 'akerl/keys'
end
expected do
github_hash
repo 'akerl/keys'
long
end
Checks a Formula file for the current version. This uses the grep module, and expects the formula to be in ./Formula/$NAME.rb.
actual do
homebrew_formula
name 'openssh'
end
Checks a Cask file for the current version. This uses the grep module, and expects the cask to be in ./Casks/$NAME.rb.
actual do
homebrew_cask
name 'alfred'
end
Checks a repo on GitLab.com for its latest tag. Supports the regex helper.
actual do
gitlab_tag
repo 'procps-ng/procps'
end
This checks a local file's contents. Supports the Regex helper, and uses the provided regex pattern to match which line of the file to use. If no regex is specified, it will use the full first line of the file.
# Searches file for OPENSSL_VERSION = 1.0.1e and returns 1.0.1e
actual do
grep
file 'Makefile'
regex /^OPENSSL_VERSION = ([\w.-]+)$/
end
Used to parse an xpath inside a web page. Requires the nokogiri gem, and supports the Regex helper.
The easiest way to get an xpath is usually to use Chrome's Inspector to find the element you want and right click it -> Copy -> As XPath. There are some quirks, notably that nokogiri doesn't parse the tbody tag (just remove it from the xpath that Chrome provides).
# Parses the latest tag for procps-ng
expected do
url_xpath
url 'https://gitlab.com/procps-ng/procps/tags'
xpath '/html/body/div[1]/div[2]/div[2]/div/div/div[2]/ul/li[1]/div[1]/a/strong/text()'
regex /v([\d.]+)$/
end
Basic module for staticly defining a value. Useful for testing, and also for comparisons against a known state.
item do
expected do
static_test
set '0.0.3'
end
actual do
static_test
set '0.0.1'
end
end
Allows modification of result using regex. Supported by most modules, per the above modules list.
The first argument should be a regex pattern to match against the value. Note that an error will be raised if the value does not match the provided regex. An optional second value specifies the replacement string to use; the default is '\1', which will use the first capture group from your regex.
# This would convert v1.0.0 into 1.0.0
actual do
git_tag
regex /^v([\d.]+)$/
end
# And this would convert v1_0_0 into 1.0.0
actual do
git_tag
regex /^v(\d+)_(\d+)_(\d+)$/, '\1.\2.\3'
end
Allows filtering of available items. Useful for modules that must parse a list where you only care about some of the entries (like upstream repos that tag multiple packages in the same repo).
The provided argument is the regex pattern to filter the list with.
# This filters out github tags that don't match the format 1.2.3
expected do
github_tag
repo 'foo/bar'
filter /^[\d.]+$/
end
Used to chdir to a different directory before loading the state.
actual do
git_hash
dir 'submodules/important_repo'
end
Used by modules to provide authenticated access to the GitHub API. Uses the octoauth gem
Used by modules to provide access to GitLab's API, using the gitlab gem
gem install prospectus
prospectus is released under the MIT License. See the bundled LICENSE file for details.