From e3e64e30aced7644b1aadea4408a06efd93d32fc Mon Sep 17 00:00:00 2001
From: Leo <thinkabit.ukim@gmail.com>
Date: Tue, 28 May 2019 02:55:23 -0300
Subject: [PATCH] add tags for each violation found

---
 NEWS                     |  13 ++++
 alint.5.scd              | 158 ++++++++++++++++++++++++++++++---------
 apkbuild-lint            |  57 +++++++++-----
 apkbuild-lint.1.scd      |  14 ++++
 aports-lint              |  31 +++++---
 aports-lint.1.scd        |  13 ++++
 tests/apkbuild-lint.bats |  58 +++++++-------
 7 files changed, 251 insertions(+), 93 deletions(-)

diff --git a/NEWS b/NEWS
index 2eabbe0..10799e0 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,16 @@
+CHANGES with 13:
+
+- Add tags for each violation in apkbuild-lint
+- Add tags for each violation in aports-lint
+- Update documentation to add each tag to the violation
+- Fix mistake on pkgver-quoted documentation
+- Update documentation to show how to skip tests for certain tags
+- Update tests to check for the tags when using assert_match
+- Convert all output to a draft version of a stable output format
+- Add extra field on the format for the severity
+- Update documentation of the tools to add an OUTPUT chapter
+- Add missing backticks-usage tag to documentation
+
 CHANGES with 12.1:
 
 - Remove spurious section referring to a tag that never existed
diff --git a/alint.5.scd b/alint.5.scd
index b236563..8808b95 100644
--- a/alint.5.scd
+++ b/alint.5.scd
@@ -2,20 +2,56 @@ alint(5)
 
 # NAME
 
-alint - linting tags
+alint - linting labels and tags
 
 # DESCRIPTION
 
-A tag is an attribute given to each test in alint, each tag has an explanation
-of what it does and a brief on how to resolve it. each test can be skipped by 
-setting an environment variable formed by SKIP_ + the tag in uppercase with the
-dashes replaced by underscore.
+A label and a tag are 2 attributes given to each test in alint, a label is composed
+by a collection of words separated by dashes and it is meant to convey the general
+idea of what the test does. A tag is a string with AL followed by an integer, those
+being assigned in increasing order as new tests are made but never re-using old ones.
 
-# TAGS (aports-lint)
+tests can be skipped by setting an environment variable composed of SKIP_ + the label
+in uppercase with the dashes replaced by underscore or by setting an environment variable
+composed of SKIP_ + the tag.
 
-The following tags are used by the *aports-lint* program.
+# Severity
 
-## Duplicate package
+Severity is assigned to each tag and indicates how serious the violation found is:
+
+## Serious (S)
+
+Will cause problems during build or when package is delivered to users. Should be fixed
+immediately.
+
+## Important (I)
+
+Might cause problems during build or when the package is delivered to users in certain
+situations. Should be fixed soon.
+
+## Minor (M)
+
+Won't directly cause issues during build or when the package is delivered to users.
+Should be fixed when convenient
+
+# Certainty
+
+Certainty is assigned to each tag and indicates how certain a test is that the violation
+found is not a false positive
+
+## Certain (C)
+
+The test is certain that this is not a false positive
+
+## Possible (P)
+
+The test is not certain that this is a false positive, but there is a high chance it isn't
+
+# LABELS TAGS (aports-lint)
+
+The following labels and tags are used by the *aports-lint* program.
+
+## duplicate-package [AL22]
 
 The Package being introduced is already present in another repo. Solve the
 conflict by:
@@ -29,7 +65,9 @@ the wrong version of a package. E.g: if *main/foo-1-r0* and *testing/foo-2-r0* e
 and *main/bar* is updated to version 2 which requires *foo>=2-r0* then it will
 fail because it will only find *main/foo-1-r0* and not *testing/foo-2-r0*.
 
-## upper-repo-depends
+Severity: Serious, Certainty: Certain
+
+## upper-repo-depends [AL16]
 
 The package depends on a package in a upper repo. The package must be moved to 
 the upper repo or the dependency moved to the repo the package is.
@@ -39,13 +77,17 @@ depend on packages in other repos. Packages in community can depend on main
 and itself only. Packages in testing can depend on main, community and itself
 only. Packages in unmaintained can depend on package on any repo but non-free.
 
-## duplicate-depends
+Severity: Serious, Certainty: Certain
+
+## duplicate-depends [AL17]
 
 The APKBUILD has duplicate depends. One of them must be removed.
 
 Declaring duplicate dependencies is superfluous.
 
-## upper-repo-makedepends
+Severity: Minor, Certainty: Certain
+
+## upper-repo-makedepends [AL18]
 
 The package makedepends on a package in a upper repo. The package must be moved
 to the upper repo or the dependency moved to the repo the package is.
@@ -55,13 +97,17 @@ makedepend on packages in other repos. Packages in community can depend on main
 and itself only. Packages in testing can makedepend on main, community and itself
 only. Packages in unmaintained can makedepend on packages of any repo but non-free.
 
-## duplicate-makedepends
+Severity: Serious, Certainty: Certain
+
+## duplicate-makedepends [AL19]
 
 The APKBUILD has duplicate makedepends. One of them must be removed.
 
 Declaring duplicate dependencies is superfluous.
 
-## upper-repo-checkdepends
+Severity: Minor, Certainty: Certain
+
+## upper-repo-checkdepends [AL20]
 
 The package checkdepends on a package in a upper repo. The package must be moved
 to the upper repo or the dependency moved to the repo the package is.
@@ -71,57 +117,75 @@ checkdepend on packages in other repos. Packages in community can checkdepend on
 and itself only. Packages in testing can checkdepend on main, community and itself
 only. Packages in unmaintained can checkdepend on package on any repo but non-free.
 
-## duplicate-checkdepends
+Severity: Serious, Certainty: Certain
+
+## duplicate-checkdepends [AL21]
 
 The APKBUILD has duplicate checkdepends. One of them must be removed.
 
 Declaring duplicate dependencies is superfluous.
 
-## pkgname-dirname-mismatch
+Severity: Minor, Certainty: Certain
+
+## pkgname-dirname-mismatch [AL23]
 
 The pkgname variable of the APKBUILD has value *foo* but the directory in which the
 APKBUILD is found is not named *foo*
 
-## depends-makedepends-checkdepends-overlap
+Severity: Important, Certainty: Certain
+
+## depends-makedepends-checkdepends-overlap [AL24]
 
 A package is present in 2 to 3 of the 3 types of following dependencies: depends,
 makedepends and checkdepends. All of them are installed during creation of the package,
 please specify only once in the lowest common denominator location.
 
-# TAGS (apkbuild-lint)
+Severity: Important, Certainty: Certain
+
+# LABELS TAGS (apkbuild-lint)
 
-The following tags are used by the *apkbuild-lint* program
+The following labels and tags are used by the *apkbuild-lint* program
 
-## default-builddir-value
+## default-builddir-value [AL1]
 
 The value of builddir matches the default which is *$srcdir/$pkgname-$pkgver*.
 The *builddir* declaration can be removed.
 
 Starting with v2.29.0 of *abuild* the value is set automatically.
 
-## unnecessary-return-1
+Severity: Important, Certainty: Certain
+
+## unnecessary-return-1 [AL2]
 
 The APKBUILD has *|| return 1* statements. They can be safely removed.
 
 Starting with version v2.15.0 of *abuild* the building process is executed
 with *set -e* effectively adding a *|| return 1* to every command.
 
-## pkgname-quoted
+Severity: Minor, Certainity: Certain
+
+## pkgname-quoted [AL3]
 
 The APKBUILD's *pkgname* variable is quoted. It must not be quoted.
 
-## pkgver-quoted
+Severity: Minor, Certainty: Possible
 
-The APKBUILD's *pkgname* variable is quoted. It must not be quoted.
+## pkgver-quoted [AL4]
+
+The APKBUILD's *pkgver* variable is quoted. It must not be quoted.
 
-## empty-variable
+Severity: Minor, Certainty: Possible
+
+## empty-variable [AL5]
 
 The APKBUILD has variables that are empty values, they can safely be removed.
 
 Empty variables can be removed to make the APKBUILD smaller and more
 concise.
 
-## custom-variable
+Severity: Minor, Certainty: Certain
+
+## custom-variable [AL6]
 
 The APKBUILD has custom variables that are not prefixed with an underscore.
 prefix the variables with underscore.
@@ -130,20 +194,32 @@ Variables that do no affect behaviour of *abuild* should be prefixed with an
 underscore so maintainers and contributors can easily distinguish their
 importance.
 
-## indent-tabs
+Severity: Important, Certainty: Certain
+
+## indent-tabs [AL7]
 
 The APKBUILD is using spaces instead of tabs for indenting. Replace the
 spaces with tabs.
 
 APKBUILDs use tab characters (\t) not spaces for indentation.
 
-## trailing-whitespace
+Severity: Important, Certainty: Certain
+
+## trailing-whitespace [AL8]
 
 The APKBUILD has trailing whitespace characters. Remove them.
 
 Trailing whitespace is superfluous.
 
-## function-keyword
+Severity: Important, Certainty: Certain
+
+# backticks-usage [AL25]
+
+The APKBUILD uses backticks for running a shell command, use `$()` instead.
+
+Severity: Serious, Certainty: Possible
+
+## function-keyword [AL9]
 
 The APKBUILD uses the function keyword to declare a function. Use
 *function()* instead.
@@ -151,24 +227,32 @@ The APKBUILD uses the function keyword to declare a function. Use
 the function keyword is a bashism. *abuild* uses Posix-compliant
 shell with the *local* keyword.
 
-## space-before-function-parenthesis
+Severity: Serious, Certainty: Certain
+
+## space-before-function-parenthesis [AL10]
 
 The APKBUILD has a space character between the name of a function
 and the paranthesis that denote it is a function. Remove the superfluous
 space.
 
-## space after-function-parenthesis
+Severity: Important, Certainty: Certain
+
+## space after-function-parenthesis [AL11]
 
 The APKBUILD doesn't have a space after the function parenthesis or has more
 than one space. Use only one space after the function parenthesis.
 
-## newline-opening-brace
+Severity: Important, Certainty: Certain
+
+## newline-opening-brace [AL12]
 
 The APKBUILD has a newline before the opening brace of a function. Put the
 opening brace in the same line as the declaration with one space after the
 function parenthesis.
 
-## superfluous-cd-builddir
+Severity: Important, Certainty: Certain
+
+## superfluous-cd-builddir [AL13]
 
 The APKBUILD has *cd "$builddir"* statements that are superfluous. Remove them.
 
@@ -177,11 +261,17 @@ functions automatically have their working directory set to the value of
 *builddir*. It is also possible that there are 2 *cd "$builddir"* statements
 one after the other.
 
-## pkgname-has-uppercase
+Severity: Important, Certainty: Possible
+
+## pkgname-has-uppercase [AL14]
 
 pkgname has uppercase characters, pkgname must have only lowercase characters.
 
-## pkgver-has-pkgrel
+Severity: Serious, Certainty: Certain
+
+## pkgver-has-pkgrel [AL15]
 
 pkgver has *-r* followed by a number, that is reserved for the relaease of a package
 as defined by the *pkgrel* variable.
+
+Severity: Serious, Certainty: Certain
diff --git a/apkbuild-lint b/apkbuild-lint
index 2b9d497..ef858f4 100755
--- a/apkbuild-lint
+++ b/apkbuild-lint
@@ -11,9 +11,9 @@
 export LC_ALL=C
 
 scan() {
-	local rx="$1" msg="$2"
+	local rx="$1" msg="$2" tag="$3" severity="$4"
 	grep -P -Hn -e "$rx" "$apkbuild" |
-		sed "s/^\([^:]*:[^:]*:\)\(.*\)/\1 $msg/"
+		sed "s/^\([^:]*:[^:]*:\)\(.*\)/$severity:[$tag]:\1$msg/"
 }
 
 variables=$(echo -n "#.*
@@ -61,74 +61,88 @@ url" | tr '\n' '|')
 
 default_builddir_value() {
 	[ "$SKIP_DEFAULT_BUILDDIR_VALUE" ] && return 0
+	[ "$SKIP_AL1" ] && return 0
 	if [ "$builddir" = "/$pkgname-$pkgver" ]; then
-		scan '^builddir=' "builddir can be removed as it is the default value"
+		scan '^builddir=' "builddir can be removed as it is the default value" 'AL1' 'IC'
 	fi
 }
 
 unnecessary_return_1() {
 	[ "$SKIP_UNNECESSARY_RETURN_1" ] && return 0
-	scan '\|\| return 1' "|| return 1 is not required as set -e is used"
+	[ "$SKIP_AL2" ] && return 0
+	scan '\|\| return 1' "|| return 1 is not required as set -e is used" 'AL2' 'MC'
 }
 
 pkgname_quoted() {
 	[ "$SKIP_PKGNAME_QUOTED" ] && return 0
-	scan '^pkgname="[^$]+"' "pkgname must not be quoted"
+	[ "$SKIP_AL3" ] && return 0
+	scan '^pkgname="[^$]+"' "pkgname must not be quoted" 'AL3' 'MP'
 }
 
 pkgver_quoted() {
 	[ "$SKIP_PKGVER_QUOTED" ] && return 0
-	scan '^pkgver="[^$]+"' "pkgver must not be quoted"
+	[ "$SKIP_AL4" ] && return 0
+	scan '^pkgver="[^$]+"' "pkgver must not be quoted" 'AL4' 'MP'
 }
 
 empty_variable() {
 	[ "$SKIP_EMPTY_VARIABLE" ] && return 0
-	scan '^[A-Za-z0-9_]*=(""|''|)$' "variable set to empty string: \2"
+	[ "$SKIP_AL5" ] && return 0
+	scan '^[A-Za-z0-9_]*=(""|''|)$' "variable set to empty string: \2" 'AL5' 'MC'
 }
 
 custom_variable() {
 	[ "$SKIP_CUSTOM_VARIABLE" ] && return 0
+	[ "$SKIP_AL6" ] && return 0
 	scan '^(?!\s*^('"$variables"'))[^\s=-]+=' \
-		"prefix custom variable with _: \2"
+		"prefix custom variable with _: \2" 'AL6' 'IC'
 }
 
 indent_tabs() {
 	[ "$SKIP_INDENT_TABS" ] && return 0
-	scan '^  ' "indent with tabs"
+	[ "$SKIP_AL7" ] && return 0
+	scan '^  ' "indent with tabs" 'AL7' 'IC'
 }
 
 trailing_whitespace() {
 	[ "$SKIP_TRAILING_WHITESPACE" ] && return 0
-	scan '[\t ]$' "trailing whitespace"
+	[ "$SKIP_AL8" ] && return 0
+	scan '[\t ]$' "trailing whitespace" 'AL8' 'IC'
 }
 
 backticks_usage() {
 	[ "$SKIP_BACKTICKS_USAGE" ] && return 0
-	scan '[^\\]`' "use \$() instead of backticks"
+	[ "$SKIP_AL25" ] && return 0
+	scan '[^\\]`' "use \$() instead of backticks" 'AL25' 'SP'
 }
 
 function_keyword() {
 	[ "$SKIP_FUNCTION_KEYWORD" ] && return 0
-	scan '^\t*function\b' 'do not use the function keyword'
+	[ "$SKIP_AL9" ] && return 0
+	scan '^\t*function\b' 'do not use the function keyword' 'AL9' 'SC'
 }
 
 space_before_function_parenthesis() {
 	[ "$SKIP_SPACE_BEFORE_FUNCTION_PARENTHESIS" ] && return 0
-	scan '^\t*[^ ]*  *\(\)' 'do not use space before function parenthesis'
+	[ "$SKIP_AL10" ] && return 0
+	scan '^\t*[^ ]*  *\(\)' 'do not use space before function parenthesis' 'AL10' 'E'
 }
 
 space_after_function_parenthesis() {
 	[ "$SKIP_SPACE_AFTER_FUNCTION_PARENTHESIS" ] && return 0
-	scan '^\t*[^ ]*\(\)(|   *){' 'use one space after function parenthesis'
+	[ "$SKIP_AL11" ] && return 0
+	scan '^\t*[^ ]*\(\)(|   *){' 'use one space after function parenthesis' 'AL11' 'E'
 }
 
 newline_opening_brace() {
 	[ "$SKIP_NEWLINE_OPENING_BRACE" ] && return 0
-	scan '^\t*[^ ]*\(\)$' 'do not use a newline before function opening brace'
+	[ "$SKIP_AL12" ] && return 0
+	scan '^\t*[^ ]*\(\)$' 'do not use a newline before function opening brace' 'AL12' 'E'
 }
 
 superfluous_cd_builddir() {
 	[ "$SKIP_SUPERFLUOUS_CD_BUILDDIR" ] && return 0
+	[ "$SKIP_AL13" ] && return 0
 	local cds= cdscount= prevcd= phase="$1"
 
 	# All ocurrences of the 'cd' command being used
@@ -166,7 +180,10 @@ superfluous_cd_builddir() {
 		[ -z "$statement" ] && continue
 		if echo "$statement" | grep -E -q 'cd ["]?\$[{]?builddir["}]?+($| )' ; then
 			if [ "$prevcd" -eq 1 ] || [ "$cdscount" -eq 1 ] || [ "$firstcd" -eq 1 ]; then
-				printf "%s:%s: cd \"\$builddir\" can be removed in phase '%s'\\n" "$apkbuild" "$linenum" "$phase"
+				printf "W:[AL13]:%s:%s:cd \"\$builddir\" can be removed in phase '%s'\\n" \
+					"$apkbuild" \
+					"$linenum" \
+					"$phase"
 			fi
 			prevcd=1
 		else
@@ -180,12 +197,14 @@ superfluous_cd_builddir() {
 
 pkgname_has_uppercase() {
 	[ "$SKIP_PKGNAME_HAS_UPPERCASE" ] && return 0
-	scan '^pkgname=[a-z0-9\._\-]*[A-Z]' 'pkgname must not have uppercase characters'
+	[ "$SKIP_AL14" ] && return 0
+	scan '^pkgname=[a-z0-9\._\-]*[A-Z]' 'pkgname must not have uppercase characters' 'AL14' 'E'
 }
 
 pkgver_has_pkgrel() {
 	[ "$SKIP_PKGVER_HAS_PKGREL" ] && return 0
-	scan '^pkgver=[A-Za-z0-9_\-\.]*(-r|_r(?!c))' 'pkgver must not have -r or _r'
+	[ "$SKIP_AL15" ] && return 0
+	scan '^pkgver=[A-Za-z0-9_\-\.]*(-r|_r(?!c))' 'pkgver must not have -r or _r' 'AL15' 'E'
 }
 
 ret=0
@@ -220,6 +239,6 @@ for apkbuild; do
 	wait
 	else
 	echo no such apkbuild "$apkbuild" 1>&2
-	fi | sort -t: -n -k2 | grep . && ret=1
+	fi | sort -t: -V | grep . && ret=1
 done
 exit $ret
diff --git a/apkbuild-lint.1.scd b/apkbuild-lint.1.scd
index 022222d..bee71e2 100644
--- a/apkbuild-lint.1.scd
+++ b/apkbuild-lint.1.scd
@@ -18,6 +18,20 @@ of each violation that apkbuild-lint checks for.
 apkbuild-lint will print the policy violations found and exit 1, if no violations
 are found then nothing will be printed and it will exit 0.
 
+# OUTPUT
+
+apkbuild-lint will print to stdout whenever a policy violation is found in the
+following format
+
+	SEVERITYCERTAINITY:[TAG]:PATH::MSG
+
+- *SEVERITY* refers to how severe a violation is, ranging from *S* to *M*.
+- *CERTAINITY* refers to how likely it is not a false positive, ranging from *C* to *P*
+- *TAG* refers to the tag of the violation, see *alint(5)* for more details.
+- *PATH* refers to the path given for *apkbuild-lint* to check.
+- *LINE* refers to the number of the line where the violation was found.
+- *MSG* is a short message meant for humans to know what is the violation.
+
 # AUTHORS
 
 Maintained by Leo <thinkabit.ukim@gmail.com>
diff --git a/aports-lint b/aports-lint
index f040a6e..7890673 100755
--- a/aports-lint
+++ b/aports-lint
@@ -65,64 +65,72 @@ find_dupe() {
 
 upper_repo_depends() {
 	[ "$SKIP_UPPER_REPO_DEPENDS" ] && return 0
+	[ "$SKIP_AL16" ] && return 0
 	printf "%s\n" "$depends" | tr " " "\n" | tr -d "\t" | sort -u | while read -r pkg; do
 		for p in $(find_repo "$pkg" "$_repo"); do
-			printf "$apkbuild:: depends '$pkg' is in upper repo '$p'\n"
+			printf "SC:[AL17]:$apkbuild::depends '$pkg' is in upper repo '$p'\n"
 		done
 	done
 }
 
 duplicate_depends() {
 	[ "$SKIP_DUPLICATE_DEPENDS" ] && return 0
+	[ "$SKIP_AL17" ] && return 0
 	printf "%s\n" "$depends" | tr " " "\n" | tr -d "\t" | sort | uniq -d | while read -r dup; do
 		[ -z "$dup" ] && continue
-		printf "$apkbuild:: duplicate '$dup' in depends\n"
+		printf "MC:[AL17]:$apkbuild::duplicate '$dup' in depends\n"
 	done
 }
 
 upper_repo_makedepends() {
 	[ "$SKIP_UPPER_REPO_MAKEDEPENDS" ] && return 0
+	[ "$SKIP_AL18" ] && return 0
 	printf "%s\n" "$makedepends" | tr " " "\n" | tr -d "\t" | sort -u | while read -r pkg; do
 		for p in $(find_repo "$pkg" "$_repo"); do
-			printf "$apkbuild:: makedepends '$pkg' is in upper repo '$p'\n"
+			printf "SC:[AL18]:$apkbuild::makedepends '$pkg' is in upper repo '$p'\n"
 		done
 	done
 }
 
 duplicate_makedepends() {
 	[ "$SKIP_DUPLICATE_MAKEDEPENDS" ] && return 0
+	[ "$SKIP_AL19" ] && return 0
 	printf "%s\n" "$makedepends" | tr " " "\n" | tr -d "\t" | sort | uniq -d | while read -r dup; do
 		[ -z "$dup" ] && continue
-		printf "$apkbuild:: duplicate '$dup' in makedepends\n"
+		printf "MC:[AL19]:$apkbuild::duplicate '$dup' in makedepends\n"
 	done
 }
 
 upper_repo_checkdepends() {
 	[ "$SKIP_UPPER_REPO_CHECKDEPENDS" ] && return 0
+	[ "$SKIP_AL20" ] && return 0
 	printf "%s\n" "$checkdepends" | tr " " "\n" | tr -d "\t" | sort -u | while read -r pkg; do
 		for p in $(find_repo "$pkg" "$_repo"); do
-			printf "$apkbuild:: checkdepends '$pkg' is in upper repo '$p'\n"
+			printf "SC:[AL20]:$apkbuild::checkdepends '$pkg' is in upper repo '$p'\n"
 		done
 	done
 }
 
 duplicate_checkdepends() {
 	[ "$SKIP_DUPLICATE_CHECKDEPENDS" ] && return 0
+	[ "$SKIP_AL21" ] && return 0
 	printf "%s\n" "$checkdepends" | tr " " "\n" | tr -d "\t" | sort | uniq -d | while read -r dup; do
 		[ -z "$dup" ] && continue
-		printf "$apkbuild:: duplicate '$dup' in checkdepends\n"
+		printf "MC:[AL21]:$apkbuild::duplicate '$dup' in checkdepends\n"
 	done
 }
 
 duplicate_package() {
 	[ "$SKIP_DUPLICATE_PACKAGE" ] && return 0
+	[ "$SKIP_AL22" ] && return 0
 	for _r in $(find_dupe "$pkgname" "$_repo"); do
-		printf "$apkbuild:: package is already present in $_r\n"
+		printf "SC:[AL22]:$apkbuild::package is already present in $_r\n"
 	done
 }
 
 pkgname_dirname_mismatch() {
 	[ "$SKIP_PKGNAME_DIRNAME_MISMATCH" ] && return 0
+	[ "$SKIP_AL23" ] && return 0
 	local _dirname=
 	case "${apkbuild%%/*}" in
 		main|community|testing|unmaintained|non-free)
@@ -132,25 +140,26 @@ pkgname_dirname_mismatch() {
 		*) return 0 ;;
 	esac
 	if [ "$pkgname" != "$_dirname" ]; then
-		printf "$apkbuild:: pkgname is '$pkgname' but is in directory '$_dirname'\n"
+		printf "IC:[AL23]:$apkbuild::pkgname is '$pkgname' but is in directory '$_dirname'\n"
 	fi
 }
 
 depends_makedepends_checkdepends_overlap() {
 	[ "$SKIP_DEPENDS_MAKEDEPENDS_CHECKDEPENDS_OVERLAP" ] && return 0
+	[ "$SKIP_AL24" ] && return 0
 	local _mkdeps _ckdeps d
 	_mkdeps="$(echo $makedepends | tr " " "\\n" | tr -d "\t" | sort -u)"
 	_ckdeps="$(echo $checkdepends | tr " " "\\n" | tr -d "\t" | sort -u)"
 	[ -z "$_mkdeps" ] && [ -z "$_ckdeps" ] && return 0
 	for d in $depends; do
 		if printf "%s\\n" "$_mkdeps" | grep -q "^$d$"; then
-			printf "%s:: dependency '%s' is in depends and makedepends\n" "$apkbuild" "$d"
+			printf "IC:[AL24]:%s::dependency '%s' is in depends and makedepends\n" "$apkbuild" "$d"
 		fi
 
 		# Don't check against checkdepends if it is empty
 		[ -z "$checkdepends" ] && continue
 		if printf "%s\\n" "$_ckdeps" | grep -q "^$d$"; then
-			printf "%s:: dependency '%s' is in depends and checkdepends\n" "$apkbuild" "$d"
+			printf "IC:[AL24]:%s::dependency '%s' is in depends and checkdepends\n" "$apkbuild" "$d"
 		fi
 	done
 
@@ -159,7 +168,7 @@ depends_makedepends_checkdepends_overlap() {
 	[ -z "$checkdepends" ] && return 0
 	for d in $makedepends; do
 		if printf "%s\\n" "$_ckdeps" | grep -q "^$d$"; then
-			printf "%s:: dependency '%s' is in makedepends and checkdepends\n" "$apkbuild" "$d"
+			printf "IC:[AL24]:%s::dependency '%s' is in makedepends and checkdepends\n" "$apkbuild" "$d"
 		fi
 	done
 }
diff --git a/aports-lint.1.scd b/aports-lint.1.scd
index 0415eed..4b946d6 100644
--- a/aports-lint.1.scd
+++ b/aports-lint.1.scd
@@ -18,6 +18,19 @@ for an explanation of each violation that aports-lint checks for.
 aports-lint will print the policy violations found and exit 1, if no violations
 are found then nothing will be printed and it will exit 0.
 
+# OUTPUT
+
+aports-lint will print to stdout whenever a policy violation is found in the
+following format
+
+	SEVERITYCERTAINITY:[TAG]:PATH::MSG
+
+- *SEVERITY* refers to how severe a violation is, ranging from *S* to *M*.
+- *CERTAINITY* refers to how likely it is not a false positive, ranging from *C* to *P*
+- *TAG* refers to the tag of the violation, see *alint(5)* for more details.
+- *PATH* refers to the path given for *apkbuild-lint* to check.
+- *MSG* is a short message meant for humans to know what is the violation.
+
 # AUTHORS
 
 Maintained by Leo <thinkabit.ukim@gmail.com>
diff --git a/tests/apkbuild-lint.bats b/tests/apkbuild-lint.bats
index 72a93a0..d5c89df 100644
--- a/tests/apkbuild-lint.bats
+++ b/tests/apkbuild-lint.bats
@@ -27,7 +27,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "builddir"
+	assert_match "${lines[0]}" "\[AL1\].*:builddir can be removed as it is the default value"
 }
 
 @test 'cd \"\$builddir\" is not highlighted' {
@@ -72,7 +72,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "builddir.*can be removed"
+	assert_match "${lines[0]}" "\[AL13\].*builddir\" can be removed in phase"
 }
 
 @test 'cd \"\$builddir\" with brackets and no quotes should be detected' {
@@ -87,7 +87,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "builddir.*can be removed"
+	assert_match "${lines[0]}" "\[AL13\].*builddir\" can be removed in phase"
 }
 
 @test 'cd \"\$builddir\" without quotes should be detected' {
@@ -102,7 +102,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "builddir.*can be removed"
+	assert_match "${lines[0]}" "\[AL13\].*builddir\" can be removed in phase"
 }
 
 @test 'cd \"\$builddir\" should be highlighted if it is also the first' {
@@ -118,8 +118,8 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "builddir.*can be removed"
-	assert_match "${lines[1]}" "builddir.*can be removed"
+	assert_match "${lines[0]}" "\[AL13\].*builddir\" can be removed in phase"
+	assert_match "${lines[1]}" "\[AL13\].*builddir\" can be removed in phase"
 }
 
 @test 'unnecessary || return 1 can be removed' {
@@ -134,7 +134,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "return 1"
+	assert_match "${lines[0]}" "\[AL2\].*|| return 1 is not required as set -e is used"
 }
 
 @test 'plain pkgname should not be quoted' {
@@ -145,7 +145,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgname.*quoted"
+	assert_match "${lines[0]}" "\[AL3\].*:pkgname must not be quoted"
 }
 
 @test 'quoted composed pkgname is fine' {
@@ -169,7 +169,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgver.*quoted"
+	assert_match "${lines[0]}" "\[AL4\].*:pkgver must not be quoted"
 }
 
 @test 'empty global variable can be removed' {
@@ -181,7 +181,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "variable.*empty"
+	assert_match "${lines[0]}" "\[AL5\].*:variable set to empty string: "
 }
 
 @test 'custom global variables should start with an underscore' {
@@ -193,7 +193,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "prefix.*_"
+	assert_match "${lines[0]}" "\[AL6\].*:prefix custom variable with _: "
 }
 
 @test 'indentation should be with tabs' {
@@ -208,7 +208,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "indent.*tabs"
+	assert_match "${lines[0]}" "\[AL7\].*:indent with tabs"
 }
 
 @test 'trailing whitespace should be removed' {
@@ -223,7 +223,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "trailing whitespace"
+	assert_match "${lines[0]}" "\[AL8\].*:trailing whitespace"
 }
 
 @test 'prefer \$() to backticks' {
@@ -238,7 +238,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "instead of backticks"
+	assert_match "${lines[0]}" "\[AL25\].*:use.*instead of backticks"
 }
 
 @test 'backticks in comments should be ignored' {
@@ -271,7 +271,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "function keyword"
+	assert_match "${lines[0]}" "\[AL9\].*:do not use the function keyword"
 }
 
 @test 'no space between function name and parenthesis' {
@@ -286,7 +286,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "before function parenthesis"
+	assert_match "${lines[0]}" "\[AL10\].*:do not use space before function parenthesis"
 }
 
 @test 'one space after function parenthesis' {
@@ -301,7 +301,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "after function parenthesis"
+	assert_match "${lines[0]}" "\[AL11\].*:use one space after function parenthesis"
 }
 
 @test 'opening brace for function should be on the same line' {
@@ -317,7 +317,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "newline before function"
+	assert_match "${lines[0]}" "\[AL12\].*:do not use a newline before function opening brace"
 }
 
 @test 'cd to builddir dir without cd to other dir can be removed' {
@@ -333,7 +333,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "builddir.*can be removed"
+	assert_match "${lines[0]}" "\[AL13\].*builddir.*can be removed in phase"
 }
 
 @test 'pkgname must not have uppercase characters' {
@@ -350,7 +350,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgname must not have uppercase characters"
+	assert_match "${lines[0]}" "\[AL14\].*:pkgname must not have uppercase characters"
 
 	cat <<-"EOF" >$apkbuild
 	pkgname=foo-FONT
@@ -358,7 +358,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgname must not have uppercase characters"
+	assert_match "${lines[0]}" "\[AL14\].*:pkgname must not have uppercase characters"
 
 	cat <<-"EOF" >$apkbuild
 	pkgname=f_oO
@@ -366,14 +366,14 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgname must not have uppercase characters"
+	assert_match "${lines[0]}" "\[AL14\].*:pkgname must not have uppercase characters"
 	cat <<-"EOF" >$apkbuild
 	pkgname=f.o.O
 	EOF
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgname must not have uppercase characters"
+	assert_match "${lines[0]}" "\[AL14\].*:pkgname must not have uppercase characters"
 
 	cat <<-"EOF" >$apkbuild
 	pkgname=9Foo
@@ -381,7 +381,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgname must not have uppercase characters"
+	assert_match "${lines[0]}" "\[AL14\].*:pkgname must not have uppercase characters"
 
 	cat <<-"EOF" >$apkbuild
 	pkgname=FoO
@@ -389,7 +389,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgname must not have uppercase characters"
+	assert_match "${lines[0]}" "\[AL14\].*:pkgname must not have uppercase characters"
 }
 
 @test 'pkgver must not have -rN' {
@@ -408,7 +408,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgver must not have -r or _r"
+	assert_match "${lines[0]}" "\[AL15\].*:pkgver must not have -r or _r"
 
 	cat <<-"EOF" >$apkbuild
 	pkgname=foo
@@ -417,7 +417,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgver must not have -r or _r"
+	assert_match "${lines[0]}" "\[AL15\].*:pkgver must not have -r or _r"
 
 	cat <<-"EOF" >$apkbuild
 	pkgname=foo
@@ -426,7 +426,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgver must not have -r or _r"
+	assert_match "${lines[0]}" "\[AL15\].*:pkgver must not have -r or _r"
 }
 
 @test 'pkgver can have _rc but not -rc' {
@@ -445,7 +445,7 @@ is_travis() {
 
 	run $cmd $apkbuild
 	[[ $status -eq 1 ]]
-	assert_match "${lines[0]}" "pkgver must not have -r or _r"
+	assert_match "${lines[0]}" "\[AL15\].*:pkgver must not have -r or _r"
 }
 
 # vim: noexpandtab
-- 
2.26.2