List policies exhaustively in .perlcriticrc and enforce this.

.perlcriticrc now explicitly mentions every single policy that is
available from the policy packages we use, as either enabled or
disabled.  Furthermore .perlcriticrc lists, in comments, all of the
expected policy sets and related distributions that should be
available, with version pins; this is now the canonical home for this
information.

A new ancillary script, build-aux/check-perlcritic-config, validates
that the list of policies in .perlcriticrc is 1:1 with the set of
available policies.  It is run by ‘make distcheck.’  (Todo: convert to
a local perlcritic policy so that every run of perlcritic does this
validation.)

These changes will hopefully prevent future problems along the lines
of 5ad98a9dca84f064e7dc19049afbc478d7320f97 (reverted by
55880f9d2e057b83ccaf29132f01a16d7285a7a7), where two developers did
not have the same set of perlcritic policies installed and therefore
disagreed on whether a ‘no critic’ annotation was necessary.  They
will also ensure that the set of perlcritic policies being tested in
CI is exactly what we expect.

The downside of this change is that .perlcriticrc is now harder to
read through and find all the policies with configuration.  Better
ideas for organizing it are welcomed.

1 files changed, 76 insertions, 0 deletions

diff --git a/build-aux/check-perlcritic-config b/build-aux/check-perlcritic-config
new file mode 100755
index 0000000..54b458f
--- /dev/null
+++ b/build-aux/check-perlcritic-config
@@ -0,0 +1,76 @@
+#! /usr/bin/perl
+# Written by Zack Weinberg <zackw at panix.com> in 2021.
+# To the extent possible under law, Zack Weinberg has waived all
+# copyright and related or neighboring rights to this work.
+#
+# See https://creativecommons.org/publicdomain/zero/1.0/ for further
+# details.
+
+# Compare the set of available Perl::Critic policies with the set of
+# policies mentioned in .perlcriticrc.  Fail the build if there are
+# available policies that are not mentioned, or mentioned policies
+# that are not available.  This ensures that we always have the
+# expected set of policies available when running perlcritic, and
+# that we have thought about whether each one _should_ be enabled.
+# ("Mentioned" does not mean "enabled".  [-APolicy::WeDontWantToUse]
+# counts as mentioning the policy for purpose of this script.)
+
+# Ideally this would be a perlcritic policy itself, so it would get
+# run on any invocation of perlcritic, not just on 'make distcheck'.
+
+use v5.14;    # implicit use strict, use feature ':5.14'
+use warnings FATAL => 'all';
+use utf8;
+use open qw(:std :utf8);
+no  if $] >= 5.022, warnings => 'experimental::re_strict';
+use if $] >= 5.022, re       => 'strict';
+
+use Perl::Critic              ();
+use Perl::Critic::UserProfile ();
+
+sub all_policies {
+    return
+        map { ("$_" => 1) }
+        Perl::Critic->new(-profile => q(), -severity => 1)->policies();
+}
+
+sub mentioned_policies {
+    return
+        map { (s/^Perl::Critic::Policy:://r => 1) }
+        Perl::Critic::UserProfile->new()->listed_policies();
+}
+
+sub compare_mentioned_to_all {
+    my %all       = all_policies();
+    my %mentioned = mentioned_policies();
+
+    my @unmentioned;
+    for my $p (keys %all) {
+        push @unmentioned, $p unless exists $mentioned{$p};
+    }
+
+    my @uninstalled;
+    for my $p (keys %mentioned) {
+        push @uninstalled, $p unless exists $all{$p};
+    }
+
+    my $fail = 0;
+    if (@unmentioned) {
+        print {*STDERR}
+            "*** Unmentioned policies:\n\t",
+            join("\n\t", sort @unmentioned),
+            "\n\n";
+        $fail = 1;
+    }
+    if (@uninstalled) {
+        print {*STDERR}
+            "*** Uninstalled policies:\n\t",
+            join("\n\t", sort @uninstalled),
+            "\n\n";
+        $fail = 1;
+    }
+
+    return $fail;
+}
+
+exit compare_mentioned_to_all();