t: add check-grep to detect bare grep assertions

Add check-grep.pl, a lint tool that detects bare 'grep' used as
a test assertion where 'test_grep' should be used instead, and
'! test_grep' where 'test_grep !' should be used (shell negation
suppresses the diagnostic output).  Wire it into the test-lint
target as test-lint-grep.

The checker reuses chainlint's shared shell parser to correctly
identify command boundaries, so 'grep' appearing as an argument
to another command, in heredoc bodies, command substitutions, or
strings is not flagged.

Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>

Author: mmontalbo

t/Makefile

@@ -139,7 +139,7 @@ check-meson:
 test-lint: test-lint-duplicates test-lint-executable \
 	test-lint-filenames
 ifneq ($(PERL_PATH),)
-test-lint: test-lint-shell-syntax
+test-lint: test-lint-shell-syntax test-lint-grep
 else
 GIT_TEST_CHAIN_LINT = 0
 endif
@@ -157,6 +157,9 @@ test-lint-executable:
 		test -z "$$bad" || { \
 		echo >&2 "non-executable tests:" $$bad; exit 1; }
 
+test-lint-grep:
+	@'$(PERL_PATH_SQ)' check-grep.pl $(T) $(TPERF)
+
 test-lint-shell-syntax:
 	@'$(PERL_PATH_SQ)' check-non-portable-shell.pl $(T) $(THELPERS) $(TPERF)
 

t/check-grep.pl

@@ -0,0 +1,137 @@
+#!/usr/bin/perl
+
+# Detect bare 'grep' used as a test assertion where 'test_grep'
+# should be used, and '! test_grep' where 'test_grep !' should
+# be used.  Uses the shared shell parser to correctly identify
+# command boundaries, avoiding false positives from 'grep' in
+# arguments, strings, heredocs, or command substitutions.
+
+use strict;
+use warnings;
+use File::Basename;
+
+my $_lib = dirname($0) . "/lib-shell-parser.pl";
+$_lib = "./$_lib" unless $_lib =~ m{^/};
+do $_lib or die "$0: failed to load $_lib: $@$!\n";
+
+my $exit_code = 0;
+
+package CheckGrepParser;
+our @ISA = ('ScriptParser');
+
+sub check_test {
+	my $self = shift @_;
+	my $title = ScriptParser::unwrap(shift @_);
+	my $body = shift @_;
+	my $lineno = $body->[3];
+	$body = ScriptParser::unwrap($body);
+	if ($body eq '-') {
+		my $herebody = shift @_;
+		if ($herebody) {
+			$body = $herebody->{content};
+			$lineno = $herebody->{start_line};
+		}
+	}
+	return unless $body;
+
+	my $parser = ShellParser->new(\$body);
+	my @tokens = $parser->parse();
+
+	my $raw_lines = $self->{raw_lines};
+
+	# Check if the raw source line has a lint-ok annotation.
+	# Also check adjacent lines to handle backslash-continuation
+	# line number offsets from the parser.
+	sub _lint_ok {
+		my ($raw_lines, $ln) = @_;
+		for my $l ($ln - 1, $ln, $ln + 1) {
+			next if $l < 1 || $l > @$raw_lines;
+			return 1 if $raw_lines->[$l - 1] =~ /lint-ok/;
+		}
+		return 0;
+	}
+
+	# Check if the grep at position $pos pipes its output
+	# or redirects I/O (i.e. used as a filter, not assertion).
+	sub _is_filter {
+		my ($tokens, $pos) = @_;
+		for (my $j = $pos + 1; $j < @$tokens; $j++) {
+			my $t = $tokens->[$j]->[0];
+			return 0 if $t =~ /^(?:&&|\|\||;;|\n)$/;
+			return 1 if $t eq '|';
+			return 1 if $t =~ /^>{1,2}$/;
+			return 1 if $t eq '<';
+		}
+		return 0;
+	}
+
+	# Walk the token stream.  Track command boundaries to
+	# identify 'grep' as a command word (not an argument).
+	my $cmd_pos = 1;
+	my $in_pipe = 0;
+	my $file = $self->{file};
+
+	for (my $i = 0; $i < @tokens; $i++) {
+		my $text = $tokens[$i]->[0];
+		my $ln = ($tokens[$i]->[3] || 0) + ($lineno || 1) - 1;
+
+		# command separators: next token is a command word
+		if ($text =~ /^(?:&&|\|\||;;|\n)$/ ||
+		    $text =~ /^[{(]$/ ||
+		    $text =~ /^(?:do|then|else|elif)$/) {
+			$cmd_pos = 1;
+			$in_pipe = 0 if $text =~ /^(?:&&|\|\||;;)$/;
+			next;
+		}
+		if ($text eq '|') {
+			$cmd_pos = 1;
+			$in_pipe = 1;
+			next;
+		}
+		if ($text =~ /^[})]$/) {
+			$cmd_pos = 0;
+			next;
+		}
+
+		next unless $cmd_pos;
+
+		# '!' is a negation prefix, stay in command position
+		if ($text eq '!') {
+			if ($i + 1 < @tokens &&
+			    $tokens[$i + 1]->[0] eq 'test_grep' &&
+			    !_lint_ok($raw_lines, $ln)) {
+				print "$file:$ln: error: ",
+				    'use "test_grep !" instead of ',
+				    '"! test_grep"', "\n";
+				$exit_code = 1;
+			}
+			next;
+		}
+
+		# bare grep at command position, not in a pipeline
+		if ($text eq 'grep' && !$in_pipe &&
+		    !_is_filter(\@tokens, $i) &&
+		    !_lint_ok($raw_lines, $ln)) {
+			print "$file:$ln: error: ",
+			    "bare grep outside pipeline ",
+			    "(use test_grep)\n";
+			$exit_code = 1;
+		}
+
+		$cmd_pos = 0;
+	}
+}
+
+package main;
+
+for my $file (@ARGV) {
+	open(my $fh, '<:unix:crlf', $file) or die "$0: $file: $!\n";
+	my @raw_lines = <$fh>;
+	close $fh;
+	my $s = join('', @raw_lines);
+	my $parser = CheckGrepParser->new(\$s);
+	$parser->{file} = $file;
+	$parser->{raw_lines} = \@raw_lines;
+	$parser->parse();
+}
+exit $exit_code;