[PATCH v3] checkpatch: improve email parsing

From: Dwaipayan Ray
Date: Thu Nov 05 2020 - 07:00:25 EST


checkpatch doesn't report warnings for many common mistakes
in emails. Some of which are trailing commas and incorrect
use of email comments.

At the same time several false positives are reported due to
incorrect handling of mail comments. The most common of which
is due to the pattern:

<stable@xxxxxxxxxxxxxxx> # X.X

Improve email parsing in checkpatch.

Some general comment rules are defined:

- Multiple name comments should not be allowed.
- Comments inside address should not be allowed.
- In general comments should be enclosed within parentheses.
Exception for stable@xxxxxxxxxxxxxxx # X.X

Improvements to parsing:

- Detect and report unexpected content after email.
- Quoted names are excluded from comment parsing.
- Trailing dots or commas in email are removed during
formatting. Correspondingly a BAD_SIGN_OFF warning
is emitted.
- Improperly quoted email like '"name <address>"' are now
warned about.

In addition, added fixes for all the possible rules.

Signed-off-by: Dwaipayan Ray <dwaipayanray1@xxxxxxxxx>
---
scripts/checkpatch.pl | 88 ++++++++++++++++++++++++++++++++++---------
1 file changed, 71 insertions(+), 17 deletions(-)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index fab38b493cef..dc8b664b7de1 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -1152,6 +1152,7 @@ sub parse_email {
my ($formatted_email) = @_;

my $name = "";
+ my $quoted = "";
my $name_comment = "";
my $address = "";
my $comment = "";
@@ -1183,14 +1184,20 @@ sub parse_email {
}
}

- $comment = trim($comment);
- $name = trim($name);
- $name =~ s/^\"|\"$//g;
- if ($name =~ s/(\s*\([^\)]+\))\s*//) {
- $name_comment = trim($1);
+ # Extract comments from names excluding quoted parts
+ # "John A. (Kennedy)" - Do not extract
+ if ($name =~ s/\"(.+)\"//) {
+ $quoted = $1;
+ }
+ while ($name =~ s/\s*($balanced_parens)\s*/ /) {
+ $name_comment .= trim($1);
}
+ $name =~ s/^[ \"]+|[ \"]+$//g;
+ $name = trim("$quoted $name");
+
$address = trim($address);
$address =~ s/^\<|\>$//g;
+ $comment = trim($comment);

if ($name =~ /[^\w \-]/i) { ##has "must quote" chars
$name =~ s/(?<!\\)"/\\"/g; ##escape quotes
@@ -1205,17 +1212,20 @@ sub format_email {

my $formatted_email;

- $name_comment = trim($name_comment);
- $comment = trim($comment);
- $name = trim($name);
- $name =~ s/^\"|\"$//g;
+ $name =~ s/^[ \"]+|[ \"]+$//g;
$address = trim($address);
+ $address =~ s/(?:\.|\,)+$//; ##trailing commas or dots

if ($name =~ /[^\w \-]/i) { ##has "must quote" chars
$name =~ s/(?<!\\)"/\\"/g; ##escape quotes
$name = "\"$name\"";
}

+ $name_comment = trim($name_comment);
+ $name_comment = " $name_comment" if length($name_comment) > 0;
+ $comment = trim($comment);
+ $comment = " $comment" if length($comment) > 0;
+
if ("$name" eq "") {
$formatted_email = "$address";
} else {
@@ -1233,15 +1243,11 @@ sub reformat_email {
}

sub same_email_addresses {
- my ($email1, $email2, $match_comment) = @_;
+ my ($email1, $email2) = @_;

my ($email1_name, $name1_comment, $email1_address, $comment1) = parse_email($email1);
my ($email2_name, $name2_comment, $email2_address, $comment2) = parse_email($email2);

- if ($match_comment != 1) {
- return $email1_name eq $email2_name &&
- $email1_address eq $email2_address;
- }
return $email1_name eq $email2_name &&
$email1_address eq $email2_address &&
$name1_comment eq $name2_comment &&
@@ -2704,7 +2710,7 @@ sub process {
$signoff++;
$in_commit_log = 0;
if ($author ne '' && $authorsignoff != 1) {
- if (same_email_addresses($1, $author, 1)) {
+ if (same_email_addresses($1, $author)) {
$authorsignoff = 1;
} else {
my $ctx = $1;
@@ -2800,9 +2806,57 @@ sub process {
$dequoted =~ s/" </ </;
# Don't force email to have quotes
# Allow just an angle bracketed address
- if (!same_email_addresses($email, $suggested_email, 0)) {
+ if (!same_email_addresses($email, $suggested_email)) {
+ if (WARN("BAD_SIGN_OFF",
+ "email address '$email' might be better as '$suggested_email'\n" . $herecurr) &&
+ $fix) {
+ $fixed[$fixlinenr] =~ s/\Q$email\E/$suggested_email/;
+ }
+ }
+
+ # Address part shouldn't have comments
+ my $stripped_address = $email_address;
+ $stripped_address =~ s/\([^\(\)]*\)//g;
+ if ($email_address ne $stripped_address) {
+ if (WARN("BAD_SIGN_OFF",
+ "address part of email should not have comments: '$email_address'\n" . $herecurr) &&
+ $fix) {
+ $fixed[$fixlinenr] =~ s/\Q$email_address\E/$stripped_address/;
+ }
+ }
+
+ # Only one name comment should be allowed
+ my $comment_count = () = $name_comment =~ /\([^\)]+\)/g;
+ if ($comment_count > 1) {
WARN("BAD_SIGN_OFF",
- "email address '$email' might be better as '$suggested_email'\n" . $herecurr);
+ "Use a single name comment in email: '$email'\n" . $herecurr);
+ }
+
+ # Comments must begin only with (
+ # or # in case of stable@xxxxxxxxxxxxxxx
+ if ($email =~ /^.*stable\@vger/) {
+ if ($comment ne "" && $comment !~ /^#.+/) {
+ if (WARN("BAD_SIGN_OFF",
+ "Invalid comment format for stable: '$email', prefer parentheses\n" . $herecurr) &&
+ $fix) {
+ my $new_comment = $comment;
+ $new_comment =~ s/^[ \(\[]+|[ \)\]]+$//g;
+ $new_comment = " # $new_comment" if length($new_comment) > 0;
+ $fixed[$fixlinenr] =~ s/\s*\Q$comment\E$/$new_comment/;
+ }
+ }
+ } else {
+ if ($comment ne "" && $comment !~ /^\(.+\)$/) {
+ if (WARN("BAD_SIGN_OFF",
+ "Unexpected content after email: '$email'\n" . $herecurr) &&
+ $fix) {
+ my $new_comment = $comment;
+ $new_comment =~ s/^(?:\#|\/\*|\.|\,)//g;
+ $new_comment =~ s/^[ \{\[]+|[ \}\]]+$//g;
+ $new_comment = " ($new_comment)" if length($new_comment) > 0;
+ $fixed[$fixlinenr] =~ s/\s*\Q$comment\E$/$new_comment/;
+ }
+ }
}
}

--
2.27.0