add tags for each violation found

NEWS

+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

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

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

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>

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