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) $(THELPERS) $(TPERF)
+
 test-lint-shell-syntax:
 	@'$(PERL_PATH_SQ)' check-non-portable-shell.pl $(T) $(THELPERS) $(TPERF)
 

t/check-grep.pl

@@ -0,0 +1,141 @@
+#!/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');
+
+# Tokens that mark the start of a new command.
+my %cmd_start;
+@cmd_start{qw(&& || ;; do then else elif), "\n", '{', '('} = ();
+
+# Subset of cmd_start that also ends a pipeline.
+my %pipe_end;
+@pipe_end{qw(&& || ;;)} = ();
+
+# Tokens indicating grep is used as a filter (pipe or redirect).
+my %filter_op;
+@filter_op{'|', '>', '>>', '<'} = ();
+
+# 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 exists $cmd_start{$t};
+		return 1 if exists $filter_op{$t};
+	}
+	return 0;
+}
+
+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};
+	my $file = $self->{file};
+	my $cmd_pos = 1;
+	my $in_pipe = 0;
+
+	for (my $i = 0; $i < @tokens; $i++) {
+		my $text = $tokens[$i]->[0];
+		my $ln = ($tokens[$i]->[3] || 0) + ($lineno || 1) - 1;
+
+		if (exists $cmd_start{$text}) {
+			$cmd_pos = 1;
+			$in_pipe = 0 if exists $pipe_end{$text};
+			next;
+		}
+		if ($text eq '|') {
+			$cmd_pos = 1;
+			$in_pipe = 1;
+			next;
+		}
+		if ($text eq '}' || $text eq ')') {
+			$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;