feat(version): introduce version check subcommand

The version subcommand handles pkgver related commands, the first
subcommand being `check`. Check runs nvchecker if a `.nvchecker.toml`
file exists and compares the current pkgver with the latest release.

Introduces nvchecker as optional dependency which has to be installed in
order to use this particular subcommand.

BREAKING CHANGE: formerly pkgctl version would output the version of the
pkgctl tool, now it is used as a version related subcommand.

Fixes #140

Component: pkgctl version
Component: pkgctl version check
Co-authored-by: Christian Heusel <christian@heusel.eu>

9 files changed, 202 insertions, 21 deletions

diff --git a/README.md b/README.md
index ca761db..8b85bd9 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,7 @@ Component: pkgctl db remove
 ### Optional Dependencies
 
 - bats (pretty printing)
+- nvchecker (version checking)
 
 ### Development Dependencies
 
diff --git a/contrib/completion/bash/devtools.in b/contrib/completion/bash/devtools.in
index 1fbd46c..f1084ab 100644
--- a/contrib/completion/bash/devtools.in
+++ b/contrib/completion/bash/devtools.in
@@ -337,6 +337,15 @@ _pkgctl_repo_switch_opts() {
 	fi
 }
 
+_pkgctl_version_cmds=(
+	check
+)
+
+_pkgctl_version_check_args=(
+	-h --help
+)
+
+_pkgctl_version_check_opts() { _filedir -d; }
 
 _pkgctl_repo_web_args=(
 	--print
diff --git a/contrib/completion/zsh/_devtools.in b/contrib/completion/zsh/_devtools.in
index 5b51aff..575c327 100644
--- a/contrib/completion/zsh/_devtools.in
+++ b/contrib/completion/zsh/_devtools.in
@@ -277,7 +277,7 @@ _pkgctl_cmds=(
 	"release[Release step to commit, tag and upload build artifacts]"
 	"repo[Manage Git packaging repositories and their configuration]"
 	"search[Search for an expression across the GitLab packaging group]"
-	"version[Show pkgctl version information]"
+	"version[Package version related commands]"
 )
 
 _pkgctl_args=(
@@ -285,8 +285,14 @@ _pkgctl_args=(
 	'(-h --help)'{-h,--help}'[Display usage]'
 )
 
-_pkgctl_version_args=(
+_pkgctl_version_cmds=(
+	"pkgctl version command"
+	"check[Check if there is an new upstream version available]"
+)
+
+_pkgctl_version_check_args=(
 	'(-h --help)'{-h,--help}'[Display usage]'
+	'*:git_dir:_files -/'
 )
 
 _pkgctl_diff_args=("${_diffpkg_args[@]}")
diff --git a/doc/man/pkgctl-version-check.1.asciidoc b/doc/man/pkgctl-version-check.1.asciidoc
new file mode 100644
index 0000000..97d8c47
--- /dev/null
+++ b/doc/man/pkgctl-version-check.1.asciidoc
@@ -0,0 +1,35 @@
+pkgctl-version-check(1)
+=======================
+
+Name
+----
+pkgctl-version-check - Check if there is an new upstream version available
+
+Synopsis
+--------
+pkgctl version check [OPTIONS] [PKGBASE...]
+
+Description
+-----------
+
+Uses nvchecker, a .nvchecker.toml file and the version specified in the current
+PKGBUILDs pkgver to check if there is a newer package version available to
+which this package could possibly be upgraded.
+
+The current working directory is used if no PKGBASE is specified.
+
+See the section on configuration files in **nvchecker**(1) for possible options
+which can be utilized in .nvchecker.toml.
+
+Options
+-------
+
+*-h, --help*::
+	Show a help text
+
+See Also
+--------
+
+linkman:nvchecker[1]
+
+include::include/footer.asciidoc[]
diff --git a/doc/man/pkgctl-version.1.asciidoc b/doc/man/pkgctl-version.1.asciidoc
index 9beebf5..53a72f3 100644
--- a/doc/man/pkgctl-version.1.asciidoc
+++ b/doc/man/pkgctl-version.1.asciidoc
@@ -3,16 +3,17 @@ pkgctl-version(1)
 
 Name
 ----
-pkgctl-version - Show pkgctl version information
+pkgctl-version - Package version related commands.
+
 
 Synopsis
 --------
-pkgctl version [OPTIONS]
+pkgctl version [OPTIONS] [SUBCOMMAND]
 
 Description
 -----------
 
-Shows the current version information of pkgctl.
+Package version related commands such as checking if a package is out of date.
 
 Options
 -------
@@ -20,4 +21,15 @@ Options
 *-h, --help*::
 	Show a help text
 
+Subcommands
+-----------
+
+pkgctl version check::
+	Check if there is an new upstream version available
+
+See Also
+--------
+
+linkman:pkgctl-version-check[1]
+
 include::include/footer.asciidoc[]
diff --git a/doc/man/pkgctl.1.asciidoc b/doc/man/pkgctl.1.asciidoc
index 24b0613..929ae9a 100644
--- a/doc/man/pkgctl.1.asciidoc
+++ b/doc/man/pkgctl.1.asciidoc
@@ -51,7 +51,7 @@ pkgctl search::
 	Search for an expression across the GitLab packaging group
 
 pkgctl version::
-	Show pkgctl version information
+	Package version related commands
 
 See Also
 --------
diff --git a/src/lib/version/version.sh b/src/lib/version.sh
index d00a460..826b306 100644
--- a/src/lib/version/version.sh
+++ b/src/lib/version.sh
@@ -7,41 +7,50 @@ DEVTOOLS_INCLUDE_VERSION_SH=1
 
 _DEVTOOLS_LIBRARY_DIR=${_DEVTOOLS_LIBRARY_DIR:-@pkgdatadir@}
 
-source /usr/share/makepkg/util/message.sh
-
 set -e
 
 
 pkgctl_version_usage() {
 	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
     cat <<- _EOF_
-		Usage: ${COMMAND} [OPTIONS]
+		Usage: ${COMMAND} [COMMAND] [OPTIONS]
+
+		Package version related commands.
 
-		Shows the current version information of pkgctl
+		COMMANDS
+		    check    Check if there is a newer version availble
 
 		OPTIONS
 		    -h, --help    Show this help text
-_EOF_
-}
 
-pkgctl_version_print() {
-	cat <<- _EOF_
-		pkgctl @buildtoolver@
+		EXAMPLES
+		    $ ${COMMAND} check libfoo linux libbar
 _EOF_
 }
 
 pkgctl_version() {
+	if (( $# < 1 )); then
+		pkgctl_version_usage
+		exit 0
+	fi
+
 	while (( $# )); do
 		case $1 in
 			-h|--help)
 				pkgctl_version_usage
 				exit 0
 				;;
+			check)
+				_DEVTOOLS_COMMAND+=" $1"
+				shift
+				# shellcheck source=src/lib/version/check.sh
+				source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/check.sh
+				pkgctl_version_check "$@"
+				exit 0
+				;;
 			*)
 				die "invalid argument: %s" "$1"
 				;;
 		esac
 	done
-
-	pkgctl_version_print
 }
diff --git a/src/lib/version/check.sh b/src/lib/version/check.sh
new file mode 100644
index 0000000..f6619c2
--- /dev/null
+++ b/src/lib/version/check.sh
@@ -0,0 +1,97 @@
+#!/bin/bash
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+[[ -z ${DEVTOOLS_INCLUDE_VERSION_CHECK_SH:-} ]] || return 0
+DEVTOOLS_INCLUDE_VERSION_CHECK_SH=1
+
+_DEVTOOLS_LIBRARY_DIR=${_DEVTOOLS_LIBRARY_DIR:-@pkgdatadir@}
+# shellcheck source=src/lib/common.sh
+source "${_DEVTOOLS_LIBRARY_DIR}"/lib/common.sh
+
+source /usr/share/makepkg/util/message.sh
+
+set -e
+
+pkgctl_version_check_usage() {
+	local -r COMMAND=${_DEVTOOLS_COMMAND:-${BASH_SOURCE[0]##*/}}
+	cat <<- _EOF_
+		Usage: ${COMMAND} [OPTIONS] [PKGBASE]...
+
+		Uses nvchecker, a .nvchecker.toml file and the current PKGBUILD
+		pkgver to check if there is a newer package version available.
+
+		The current working directory is used if no PKGBASE is specified.
+
+		OPTIONS
+		    -h, --help          Show this help text
+
+		EXAMPLES
+		    $ ${COMMAND} neovim vim
+_EOF_
+}
+
+pkgctl_version_check() {
+	local path
+	local pkgbases=()
+
+	while (( $# )); do
+		case $1 in
+			-h|--help)
+				pkgctl_version_check_usage
+				exit 0
+				;;
+			--)
+				shift
+				break
+				;;
+			-*)
+				die "invalid argument: %s" "$1"
+				;;
+			*)
+				pkgbases=("$@")
+				break
+				;;
+		esac
+	done
+
+	if ! command -v nvchecker &>/dev/null; then
+		die "The \"$_DEVTOOLS_COMMAND\" command requires 'nvchecker'"
+	fi
+
+	# Check if used without pkgbases in a packaging directory
+	if (( ${#pkgbases[@]} == 0 )); then
+		if [[ -f PKGBUILD ]]; then
+			pkgbases=(".")
+		else
+			pkgctl_version_check_usage
+			exit 1
+		fi
+	fi
+
+	for path in "${pkgbases[@]}"; do
+		pushd "${path}" >/dev/null
+		run_nvchecker "${path}"
+		popd >/dev/null
+	done
+}
+
+run_nvchecker() {
+	local path=$1
+	local pkgbase latest_version
+
+	if [[ ! -f ".nvchecker.toml" || ! -f "PKGBUILD" ]]; then
+		die "No .nvchecker.toml or PKGBUILD found for ${path}"
+		exit 1
+	fi
+
+	# TODO: parse .SRCINFO file
+	# shellcheck source=contrib/makepkg/PKGBUILD.proto
+	. ./PKGBUILD
+	pkgbase=${pkgbase:-$pkgname}
+
+	latest_version=$(nvchecker -c .nvchecker.toml --logger json | jq --raw-output 'select( .version ) | .version')
+	if (( $(vercmp "${latest_version}" "${pkgver}") > 0 )); then
+		msg2 "New ${pkgbase} version ${latest_version} is available upstream"
+	fi
+}
diff --git a/src/pkgctl.in b/src/pkgctl.in
index 070e0cd..9deb4b2 100644
--- a/src/pkgctl.in
+++ b/src/pkgctl.in
@@ -27,7 +27,7 @@ usage() {
 		    release Release step to commit, tag and upload build artifacts
 		    repo    Manage Git packaging repositories and their configuration
 		    search  Search for an expression across the GitLab packaging group
-		    version Show pkgctl version information
+		    version Package version related commands
 
 		OPTIONS
 		    -h, --help     Show this help text
@@ -39,6 +39,12 @@ if (( $# < 1 )); then
 	exit 1
 fi
 
+pkgctl_version_print() {
+	cat <<- _EOF_
+		pkgctl @buildtoolver@
+_EOF_
+}
+
 export _DEVTOOLS_COMMAND='pkgctl'
 
 setup_workdir
@@ -114,14 +120,20 @@ while (( $# )); do
 			pkgctl_search "$@"
 			exit 0
 			;;
-		version|--version|-V)
+		version)
 			_DEVTOOLS_COMMAND+=" $1"
 			shift
-			# shellcheck source=src/lib/version/version.sh
-			source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version/version.sh
+			# shellcheck source=src/lib/version.sh
+			source "${_DEVTOOLS_LIBRARY_DIR}"/lib/version.sh
 			pkgctl_version "$@"
 			exit 0
 			;;
+		--version|-V)
+			_DEVTOOLS_COMMAND+=" $1"
+			shift
+			pkgctl_version_print
+			exit 0
+			;;
 		*)
 			die "invalid command: %s" "$1"
 			;;