Centralize perl linters

- Mixed all linter configurations from os-autoinst, openQA,
  os-autoinst-distri-opensuse.

  Perlcritic RC & Perltidy RC files are centralized now here. For
  convenience, the most laxed rules were picked, to minimize the
  changeset size on downstream repositories.

- Improved perltidy & perlcritic wrappers

  Downstream repositories have a divergent copy of a tidyall
  wrapper that validates before that perltidy is in the correct
  version before running.

  The wrapper does *quite a lot* of text processing to assert the
  correct version of perltidy.

  The new and improved version will get the detected perltidy
  version directly from perl in a clean manner, and will invoke
  tidyall with all arguments passed to it.

  Additionally, perlcritic has a wrapper in Makefiles to inject
  a custom Perl critic policy that it's now provided in this
  repository.

  Both scripts are intended to be symlinked by downstream
  repositories that receive this repository via the subrepo flow.

  So rules can be enforced uniformly across repositories, even if
  repositories are not using the default settings provided here.

- All `openqa` themed Policies are loaded in .perlcriticrc automatically.

- Added `|` symbol as an exception to `Perl::Critic::Policy::HashKeyQuotes`.

- All CI Perl-related checks are driven by GitHub Actions. This repo offers a
  sample for Prove, Perlcritic & Tidyall.

- Tested import logic for OpenQA::Test::TimeLimit

- New perlcritic policy: Redundant strict/warnings usage. It detects if
 `use strict` is being loaded unnecessarily.

- Linter rule for use strict/warning with arguments. `use warnings` &
  `use warnings` should not include any parameters. It's now enforced with
  perlcritic.

- Add ProhibitInterpolationOfLiterals rule to .perlcriticrc
  Single quotes on strings are now enforced if they're not needed.
  If a string doesn't contain a single quote or an interpolation,
  perlcritic will require the string written with single quotes.

Co-authored-by: Tina Müller (tinita) <[email protected]>
Co-authored-by: Oliver Kurz <[email protected]>
Co-authored-by: Martchus <[email protected]>

.github/workflows/perl-lint-checks.yml

@@ -0,0 +1,26 @@
+---
+name: 'Perl Lint Checks'
+
+on:
+  pull_request:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  perl-lint-checks:
+    runs-on: ubuntu-latest
+    name: "Perltidy"
+    container:
+      image: perldocker/perl-tester:5.26
+    steps:
+      - uses: actions/checkout@v4
+      - run: GITHUB_ACTIONS=1 ./tools/tidyall --check-only --all --quiet
+  perl-critic-checks:
+    runs-on: ubuntu-latest
+    name: "Perlcritic"
+    container:
+      image: perldocker/perl-tester:5.26
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./tools/perlcritic --quiet .

.github/workflows/perl-prove.yml

@@ -0,0 +1,18 @@
+---
+name: 'Perl Testing Checks'
+
+on:
+  pull_request:
+  push:
+    branches:
+      - 'master'
+
+jobs:
+  perl-prove:
+    runs-on: ubuntu-latest
+    name: "Prove"
+    container:
+      image: perldocker/perl-tester:5.26
+    steps:
+      - uses: actions/checkout@v4
+      - run: prove .

.gitignore

@@ -0,0 +1,5 @@
+*.tdy
+.*.swp
+*~
+__pycache__/
+.tidyall.d/

.perlcriticrc

@@ -0,0 +1,49 @@
+theme = community + openqa
+severity = 4
+include = strict ValuesAndExpressions::ProhibitInterpolationOfLiterals
+
+verbose = ::warning file=%f,line=%l,col=%c,title=%m - severity %s::[%p] %e\n
+
+# == Perlcritic Policies
+# -- Test::Most brings in strict & warnings
+[TestingAndDebugging::RequireUseStrict]
+equivalent_modules = Test::Most
+
+[TestingAndDebugging::RequireUseWarnings]
+equivalent_modules = Test::Most
+
+# -- Avoid double quotes unless there's interpolation or a single quote.
+[ValuesAndExpressions::ProhibitInterpolationOfLiterals]
+allow_if_string_contains_single_quote = 1
+severity = 3
+
+# -- Prohibit deep nesting
+[ControlStructures::ProhibitDeepNests]
+severity = 4
+add_themes = community
+max_nests = 4
+
+# == Community Policies
+# -- Test::Most brings in strict & warnings
+[Freenode::StrictWarnings]
+extra_importers = Test::Most
+
+# -- Test::Most brings in strict & warnings
+[Community::StrictWarnings]
+extra_importers = Test::Most
+
+[Community::DiscouragedModules]
+severity = 3
+
+# Test modules have no package declaration
+[Community::PackageMatchesFilename]
+severity = 1
+
+# == Custom Policies
+# -- Useless quotes on hashes
+[HashKeyQuotes]
+severity = 5
+
+# -- Superfluous use strict/warning.
+[RedundantStrictWarning]
+equivalent_modules = Test::Most

.perltidyrc

@@ -0,0 +1,14 @@
+# Workaround needed for handling non-ASCII in files.
+# # See <https://github.com/houseabsolute/perl-code-tidyall/issues/84>.
+--character-encoding=none
+--no-valign
+-l=160
+-fbl     # don't change blank lines
+-fnl     # don't remove new lines
+-nsfs    # no spaces before semicolons
+-baao    # space after operators
+-bbao    # space before operators
+-pt=2    # no spaces around ()
+-bt=2    # no spaces around []
+-sbt=2   # no spaces around {}
+-sct     # stack closing tokens )}

.proverc

@@ -0,0 +1,3 @@
+--formatter TAP::Formatter::File
+--lib
+xt/

.tidyallrc

@@ -0,0 +1,3 @@
+[PerlTidy]
+select = **/*.{pl,pm,t} tools/tidyall tools/perlcritic tools/update-deps
+argv = --profile=$ROOT/.perltidyrc

README.md

@@ -1,21 +1,67 @@
 # Common files for os-autoinst/os-autoinst and os-autoinst/openQA
 
-This repository is to be used as a
-[git-subrepo](https://github.com/ingydotnet/git-subrepo).
+This repository is to be used as a [git-subrepo]
+(https://github.com/ingydotnet/git-subrepo). See the instructions below in the
+[Git Subrepo Usage](#git-subrepo-usage) section
 
+All dependencies in this project are sourced from what's available in OpenSUSE
+Tumbleweed RPM repositories.
+
+For developers not using RPM the tumbleweed repositories, a `cpanfile` is
+provided and maintained in a best-effort basis.
+
+## Tooling offered
+
+This repo offers:
+
+* Linter configuration for perl projects: `.perltidyrc`, `.perlcriticrc`,
+  `.proverc` & `.tidyallrc`.
+* Perlcritic policies that `os-autoinst/os-autoinst` and `os-autoinst/openQA`
+  share.
+* Useful tools for linting & testing:
+    * A `perlcritic` wrapper that will automatically add Perlcritic rules
+      defined under `lib/perlcritic` and
+      `external/os-autoinst-common/lib/perlcritic`.
+    * A `tidyall` wrapper that will validate the Perltidy version against the
+      `cpanfile` definition.  
+      Because `Perl::Tidy` defaults may vary between versions this tool ensures
+      the version of perltidy matches the required version specified in the
+      `cpanfile` for non-`cpanm` based installs.
+
+* Example Github Actions for linting and unit testing for Perl.
+
+All files can be either copied or symlinked for any downstream repository
+consuming these tools.
+
+## Running tools and tests from scratch
+
+```bash
+# Run a container with the project mounted in it.
+podman run -it -v "$PWD:/host/project" --workdir /host/project opensuse/leap:latest bash
+
+# Inside the container
+zypper in -y perl-App-cpanminus make gcc
+cpanm --installdeps . --with-develop
+
+prove .
+./tools/tidyall --check-only --all --quiet
+./tools/perlcritic --quiet .
+```
+
+## Git Subrepo Usage
 
 `git-subrepo` is available in the following repositories:
 
 [![Packaging status](https://repology.org/badge/vertical-allrepos/git-subrepo.svg)](https://repology.org/project/git-subrepo/versions)
 
-## Usage
-
 ### Clone
 
 To use it in your repository, you would usually do something like this:
 
-    % cd your-repo
-    % git subrepo clone [email protected]:os-autoinst/os-autoinst-common.git ext/os-autoinst-common
+```bash
+cd your-repo
+git subrepo clone [email protected]:os-autoinst/os-autoinst-common.git external/os-autoinst-common
+```
 
 This will automatically create a commit with information on what command
 was used.
@@ -27,42 +73,51 @@ The cloned repository files will be part of your actual repository, so anyone
 cloning this repo will have the files automatically without needing to use
 `git-subrepo` themselves.
 
-`ext` is just a convention, you can clone it into any directory.
+`external` is just a convention, you can clone it into any directory.
 
 It's also possible to clone a branch (or a specific tag or sha):
 
-    % git subrepo clone [email protected]:os-autoinst/os-autoinst-common.git \
-        -b branchname ext/os-autoinst-common
+```bash
+git subrepo clone [email protected]:os-autoinst/os-autoinst-common.git \
+    -b branchname external/os-autoinst-common
+```
 
-After cloning, you should see a file `ext/os-autoinst-common/.gitrepo` with
+After cloning, you should see a file `external/os-autoinst-common/.gitrepo` with
 information about the cloned commit.
 
 ### Pull
 
 To get the latest changes, you can pull:
 
-    % git subrepo pull ext/os-autoinst-common
+```bash
+git subrepo pull external/os-autoinst-common
+```
 
 If that doesn't work for whatever reason, you can also simply reclone it like
 that:
 
-    % git subrepo clone --force [email protected]:os-autoinst/os-autoinst-common.git ext/os-autoinst-common
+```bash
+git subrepo clone --force [email protected]:os-autoinst/os-autoinst-common.git \
+    external/os-autoinst-common
+```
 
 ### Making changes
 
-If you make changes in the subrepo inside of your top repo, you can simply commit
-them and then do:
+If you make changes in the subrepo inside of your top repo, you can simply
+commit them and then do:
 
-    % git subrepo push ext/os-autoinst-common
+```bash
+git subrepo push external/os-autoinst-common
+```
 
 ## git-subrepo
 
 You can find more information here:
+
 * [Repository and usage](https://github.com/ingydotnet/git-subrepo)
 * [A good comparison between subrepo, submodule and
   subtree](https://github.com/ingydotnet/git-subrepo/blob/master/Intro.pod)
 
-
 ## License
 
 This project is licensed under the MIT license, see LICENSE file for details.

cpanfile

@@ -0,0 +1,18 @@
+##################################################
+# WARNING
+# This file is autogenerated by tools/update-deps
+# from dependencies.yaml
+##################################################
+
+requires 'Storable', '>= 3.06';
+
+feature 'cover' => sub {
+    requires 'Devel::Cover';
+    requires 'Devel::Cover::Report::Codecov';
+};
+on 'develop' => sub {
+    requires 'Code::TidyAll';
+    requires 'Perl::Critic';
+    requires 'Perl::Critic::Community';
+    requires 'Perl::Tidy', '== 20230912';
+};

dependencies.yaml

@@ -0,0 +1,25 @@
+---
+# % is placeholder for section.
+# e.g.:
+#   % => develop
+#   %_requires => develop_requires
+targets:
+  # List all %_requires into a cpanfile
+  cpanfile: [main, develop, cover]
+  cpanfile-targets:
+    # save %_require into cpanfile section
+    develop: develop
+    cover: cover
+
+main_requires:
+  perl(Storable): '>= 3.06'
+
+develop_requires:
+  perl(Perl::Tidy): '== 20230912'
+  perl(Code::TidyAll):
+  perl(Perl::Critic):
+  perl(Perl::Critic::Community):
+
+cover_requires:
+  perl(Devel::Cover):
+  perl(Devel::Cover::Report::Codecov):

lib/OpenQA/Test/PatchDeparse.pm

@@ -15,20 +15,21 @@ if (
   )
 {
 
-#<<<  do not let perltidy touch this
+#<<<  do not let perltidy nor perlcritic touch this
+## no critic (TestingAndDebugging::ProhibitNoStrict)
 # This is not our code, and formatting should stay the same for
 # better comparison with new versions of B::Deparse
 # <---- PATCH
 package B::Deparse;
 no warnings 'redefine';
 no strict 'refs';
 
-*{"B::Deparse::walk_lineseq"} = sub {
+*{'B::Deparse::walk_lineseq'} = sub {
 
     my ($self, $op, $kids, $callback) = @_;
     my @kids = @$kids;
     for (my $i = 0; $i < @kids; $i++) {
-	my $expr = "";
+	my $expr = '';
 	if (is_state $kids[$i]) {
         # Patch for:
         # Use of uninitialized value $expr in concatenation (.) or string at /usr/lib/perl5/5.26.1/B/Deparse.pm line 1794.
@@ -40,7 +41,7 @@ no strict 'refs';
 	}
 	if (is_for_loop($kids[$i])) {
 	    $callback->($expr . $self->for_loop($kids[$i], 0),
-		$i += $kids[$i]->sibling->name eq "unstack" ? 2 : 1);
+		$i += $kids[$i]->sibling->name eq 'unstack' ? 2 : 1);
 	    next;
 	}
 	my $expr2 = $self->deparse($kids[$i], (@kids != 1)/2) // ''; # prevent undef $expr2
@@ -60,7 +61,5 @@ elsif ($B::Deparse::VERSION) {
     diag
       "Using B::Deparse v$B::Deparse::VERSION. If you see 'uninitialized' warnings, update patch in t/lib/OpenQA/Test/PatchDeparse.pm";
 }
-
+## use critic
 1;
-
-

lib/OpenQA/Test/TimeLimit.pm

@@ -1,25 +1,25 @@
-# Copyright 2020-2021 SUSE LLC
+# Copyright SUSE LLC
 # SPDX-License-Identifier: GPL-2.0-or-later
 
 package OpenQA::Test::TimeLimit;
 use Test::Most;
+use experimental 'signatures';
 
 my $SCALE_FACTOR = $ENV{OPENQA_TEST_TIMEOUT_SCALE_FACTOR} // 1;
 
-sub import {
-    my ($package, $limit) = @_;
+sub import ($package, $limit = undef) {
     die "$package: Need argument on import, e.g. use: use OpenQA::Test::TimeLimit '42';" unless $limit;
     # disable timeout if requested by ENV variable or running within debugger
     return if ($ENV{OPENQA_TEST_TIMEOUT_DISABLE} or $INC{'perl5db.pl'});
     $SCALE_FACTOR *= $ENV{OPENQA_TEST_TIMEOUT_SCALE_COVER} // 3 if Devel::Cover->can('report');
-    $SCALE_FACTOR *= $ENV{OPENQA_TEST_TIMEOUT_SCALE_CI}    // 2 if $ENV{CI};
-    $limit        *= $SCALE_FACTOR;
+    $SCALE_FACTOR *= $ENV{OPENQA_TEST_TIMEOUT_SCALE_CI} // 2 if $ENV{CI};
+    $limit *= $SCALE_FACTOR;
     $SIG{ALRM} = sub { BAIL_OUT "test '$0' exceeds runtime limit of '$limit' seconds\n" };
     alarm $limit;
 }
 
-sub scale_timeout {
-    return $_[0] * $SCALE_FACTOR;
+sub scale_timeout ($time) {
+    return $time * $SCALE_FACTOR;
 }
 
 1;