File Coverage

=head1 NAME

App::GHGen::PerlCustomizer - Customize Perl workflows based on project requirements

=head1 SYNOPSIS

        use App::GHGen::PerlCustomizer qw(detect_perl_requirements);

        my $requirements = detect_perl_requirements();
        # Returns: { min_version => '5.036', has_cpanfile => 1, ... }

=head1 FUNCTIONS

=head2 detect_perl_requirements()

Detect Perl version requirements and dependency-file presence in the current directory.

=head3 Purpose

Inspect the current working directory for common Perl distribution files
(C<cpanfile>, C<Makefile.PL>, C<dist.ini>, C<Build.PL>) and extract the
minimum Perl version declared in any of them.

=head3 Arguments

None.

=head3 Returns

A hash reference with the following keys, all of which are always present:

    {
        min_version    => Str | undef,  # e.g. '5.036'; undef when undetected
        has_cpanfile   => Bool,
        has_makefile_pl => Bool,
        has_dist_ini   => Bool,
        has_build_pl   => Bool,
    }

=head3 Side Effects

Reads files from the current working directory.

=head3 Usage Example

    use App::GHGen::PerlCustomizer qw(detect_perl_requirements);
    my $reqs = detect_perl_requirements();
    say $reqs->{min_version} // 'not specified';

=head3 API SPECIFICATION

=head4 Input

    # No parameters.

=head4 Output

    {
        type => 'hashref',
        keys => {
            min_version     => { type => 'scalar', optional => 1 },
            has_cpanfile    => { type => 'scalar' },
            has_makefile_pl => { type => 'scalar' },
            has_dist_ini    => { type => 'scalar' },
            has_build_pl    => { type => 'scalar' },
        },
    }

=head3 FORMAL SPECIFICATION

    detect_perl_requirements : → Requirements

    Requirements ≔ {
        min_version:     â„¤* ∪ { ⊥ },
        has_cpanfile:    ð”¹,
        has_makefile_pl: 𝔹,
        has_dist_ini:    ð”¹,
        has_build_pl:    ð”¹,
    }

    min_version ≔
        cpanfile exists ∧ version parseable from cpanfile  â†’ version
        Makefile.PL exists ∧ MIN_PERL_VERSION parseable   â†’ version
        otherwise                                           â†’ ⊥

=cut

=head2 generate_custom_perl_workflow($options)

Generate a customized Perl CI workflow and return it as a YAML string.

B<Options:>

=over 4

=item C<perl_versions> (array ref)

Explicit list of Perl versions to include in the test matrix, e.g.
C<['5.40', '5.38', '5.36']>.  Takes precedence over C<min_perl_version>
and C<max_perl_version> when supplied.

=item C<min_perl_version> (string, default C<'5.36'>)

Lowest Perl version to include in the matrix when C<perl_versions> is not
given.  Accepts both C<'5.036'> and C<'5.36'> notation.

=item C<max_perl_version> (string, default C<'5.42'>)

Highest Perl version to include in the default matrix when C<perl_versions>
is not given.  The built-in version table currently spans C<5.22> through
C<5.44>; the default produces the matrix C<5.36, 5.38, 5.40, 5.42>.

To test against B<Perl 5.44> (opt-in, not tested by default), pass
C<< max_perl_version => '5.44' >> or set C<perl_versions> explicitly:

    generate_custom_perl_workflow({ max_perl_version => '5.44' });
    # matrix: 5.36, 5.38, 5.40, 5.42, 5.44

    generate_custom_perl_workflow({ perl_versions => ['5.42', '5.44'] });
    # matrix: 5.42, 5.44

=item C<os> (array ref)

Operating systems for the build matrix.
Default: C<['ubuntu-latest', 'macos-latest', 'windows-latest']>.

=item C<timeout> (integer, default C<30>)

Value written to C<timeout-minutes> on every matrix job.

=item C<enable_linter> (boolean, default C<1>)

When true, inserts a B<"Lint and syntax check"> step after all dependency
installation steps and before the test run.  The step runs on B<every>
matrix cell (all OS and Perl version combinations) so that compile-time
errors are caught across the full version range being tested.

The step uses C<shell: perl {0}>, which works identically on Linux, macOS,
and Windows without any OS-specific branching.  It searches C<lib/> and
C<bin/> (falling back to C<.> when neither exists), loads each C<.pm> file
via C<do $file> with a stub C<@INC> handler that silently satisfies any
missing C<use> statements, and exits non-zero if any file fails.  Using
C<do $file> avoids spawning C<perl -c> subprocesses (which have
Windows command-line quoting issues) and avoids false failures caused by
missing CPAN dependencies.  B<No additional CPAN modules are required.>

=item C<enable_linter_unused> (boolean, default C<1>)

When true, appends an unused-variable check to the B<end of the lint step>
(i.e. it runs before the test run, not after).  The check installs
L<warnings::unused> from CPAN, then runs
C<PERL5OPT=-Mwarnings::unused prove -lr t/> so that variable lifetimes are
exercised at runtime (C<perl -c> is compile-only and cannot detect unused
variables).  It is gated on C<RUNNER_OS == Linux> and marked
C<continue-on-error: true> because unused-variable warnings can be
legitimately noisy on some codebases.

=item C<enable_critic> (boolean, default C<1>)

When true, adds a Perl::Critic step on the latest matrix Perl version and
C<ubuntu-latest>.

=item C<enable_coverage> (boolean, default C<1>)

When true, adds a Devel::Cover test-coverage step on the latest matrix Perl
version and C<ubuntu-latest>.

=item C<enable_perlimports> (boolean, default C<1>)

When true, adds a B<"Check imports with perlimports"> step on the latest matrix
Perl version and C<ubuntu-latest>.  The step installs L<App::perlimports> from
CPAN and runs C<perlimports --lint> across all C<.pm> files under C<lib/>.  It
is marked C<continue-on-error: true> because import hygiene warnings are
advisory; they should not block a CI run in established codebases.

=back

B<Generated step order:>

=over 4

=item 1. C<actions/checkout>

=item 2. Setup Perl via C<shogo82148/actions-setup-perl>

=item 3. Cache CPAN modules via C<actions/cache>

=item 4. Install cpanm and C<local::lib>

=item 5. Install project dependencies

=item 6. B<Lint and syntax check> — all matrix cells (when C<enable_linter> is true); the unused-variable check via C<PERL5OPT=-Mwarnings::unused> is embedded at the end of this step when C<enable_linter_unused> is true

=item 7. Run tests

=item 8. Run Perl::Critic — latest Perl + Ubuntu only (when C<enable_critic> is true)

=item 9. B<Check imports with perlimports> — latest Perl + Ubuntu only (when C<enable_perlimports> is true)

=item 10. Test coverage — latest Perl + Ubuntu only (when C<enable_coverage> is true)

=item 11. Show cpanm build log on failure

=back

=head3 API SPECIFICATION

=head4 Input

    {
        opts => {
            type     => 'hashref',
            default  => {},
            keys     => {
                perl_versions        => { type => 'arrayref', optional => 1 },
                min_perl_version     => { type => 'scalar',  default  => '5.36' },
                max_perl_version     => { type => 'scalar',  default  => '5.42' },
                os                   => { type => 'arrayref', optional => 1 },
                timeout              => { type => 'scalar',  default  => 30 },
                enable_linter        => { type => 'scalar',  default  => 1 },
                enable_linter_unused => { type => 'scalar',  default  => 1 },
                enable_critic        => { type => 'scalar',  default  => 1 },
                enable_coverage      => { type => 'scalar',  default  => 1 },
                enable_perlimports   => { type => 'scalar',  default  => 1 },
            },
        },
    }

=head4 Output

    { type => 'scalar' }   # multi-line YAML string starting with '---'

=head3 FORMAL SPECIFICATION

    generate_custom_perl_workflow : Opts → YAML

    versions ≔ opts.perl_versions ?? range(min, max)
    latest   â‰” versions[|versions|−1]

    yaml contains "Lint and syntax check" step       â†”  opts.enable_linter = 1
    yaml contains "PERL5OPT=-Mwarnings::unused"      â†”  opts.enable_linter_unused = 1
    yaml contains "Run Perl::Critic"                 â†”  opts.enable_critic = 1
    yaml contains "Test coverage"                    â†”  opts.enable_coverage = 1
    yaml contains "Check imports with perlimports"   â†”  opts.enable_perlimports = 1

    step ordering invariant:
      pos(lint) < pos(unused) < pos(tests) < pos(critic) < pos(perlimports) < pos(coverage)

=cut

=head1 LIMITATIONS

=head2 Windows + Perl 5.40 excluded from the generated matrix

The shogo82148 C<perl-5.40.4-thr-win32-x64.zip> distribution ships a
C<perl.exe> and a C<libperl540.a> from two different builds.  Any XS module
compiled against that C<libperl540.a> receives handshake key
C<0x12c00080>, but C<perl.exe> needs C<0x12d00080>.  Even
C<Win32::Process> — a core Windows XS module bundled in the zip and loaded
transitively by C<IPC::System::Simple> — fails to load with this mismatch,
so no XS-using test can pass on this combination.

Recompiling XS modules (e.g. via C<cpanm --reinstall YAML::XS>) does not
help: the compilation itself links against the broken C<libperl540.a> and
inherits the wrong key.

The generated workflow therefore includes a C<matrix.exclude> entry for
C<{os: windows-latest, perl: '5.40'}>.  This entry is only emitted when
both C<windows-latest> and C<5.40> are present in the matrix, so workflows
that restrict their OS or Perl lists are unaffected.

Remove the exclusion once the upstream shogo82148/build-perl distribution
is fixed and the C<perl.exe> and C<libperl540.a> in the 5.40.x zip are
built from the same source tree.

See L<https://github.com/shogo82148/actions-setup-perl/issues/2310> for further information.

=head1 AUTHOR

Nigel Horne E<lt>njh@nigelhorne.comE<gt>

L<https://github.com/nigelhorne>

=head1 LICENSE

Usage is subject to the GPL2 licence terms.
If you use it,
please let me know.

=cut