File Coverage

=head1 NAME

App::GHGen::Analyzer - Analyze GitHub Actions workflows

=head1 SYNOPSIS

    use App::GHGen::Analyzer qw(analyze_workflow);

    my @issues = analyze_workflow($workflow_hashref, 'ci.yml');

=head1 FUNCTIONS

=head2 find_workflows()

Find all workflow files in .github/workflows directory.
Returns a sorted list of L<Path::Tiny> objects.

=head3 Purpose

Discover every GitHub Actions workflow file under C<.github/workflows> in
the current working directory.

=head3 Arguments

None.

=head3 Returns

A sorted list of L<Path::Tiny> objects, one per C<.yml> or C<.yaml> file
found.  Returns an empty list when the directory does not exist or is empty.

=head3 Side Effects

None.  Performs read-only filesystem access.

=head3 Usage Example

    use App::GHGen::Analyzer qw(find_workflows);
    chdir '/path/to/repo';
    my @wfs = find_workflows();
    say $_->basename for @wfs;

=head3 API SPECIFICATION

=head4 Input

    # No parameters.

=head4 Output

    { type => 'array', element => { isa => 'Path::Tiny' } }

=head3 FORMAL SPECIFICATION

    FindWorkflows : → seq Path

    dir ≔ .github/workflows
    FindWorkflows ≡
        Â¬dir.exists ∨ ¬dir.is_dir  â†’  âŸ¨âŸ©
        | otherwise  â†’  sort(lex) { f ∈ dir.children ∣ f.name =~ /\.ya?ml$/i }

=cut

=head2 analyze_workflow($workflow, $filename)

Analyze a workflow hash for issues. Returns array of issue hashes.

Each issue has: C<type>, C<severity>, C<message>, and an optional C<fix>.

=head3 Purpose

Inspect a parsed GitHub Actions workflow and return a list of detected
issues covering performance, security, cost, and maintenance concerns.

=head3 Arguments

=over 4

=item C<$workflow> (HashRef, required)

A hash reference representing the parsed workflow (e.g. from C<YAML::XS::LoadFile>).
Must contain at least a C<jobs> key whose value is a hash of job definitions.

=item C<$filename> (Str, required)

The filename of the workflow, used only as context in issue messages.

=back

=head3 Returns

A list (not an array reference) of issue hash references.  Each issue has:

    {
        type     => Str,  # 'performance' | 'security' | 'cost' | 'maintenance'
        severity => Str,  # 'high' | 'medium' | 'low'
        message  => Str,
        fix      => Str,  # optional: suggested YAML snippet
    }

Returns an empty list when no issues are detected.

=head3 Side Effects

None.  Pure function; does not modify its arguments.

=head3 Usage Example

    use App::GHGen::Analyzer qw(analyze_workflow);
    use YAML::XS qw(LoadFile);

    my $wf     = LoadFile('.github/workflows/ci.yml');
    my @issues = analyze_workflow($wf, 'ci.yml');
    for my $issue (@issues) {
        say "$issue->{severity}: $issue->{message}";
    }

=head3 API SPECIFICATION

=head4 Input

    {
        workflow => { type => 'hashref', required => 1 },
        filename => { type => 'scalar',  required => 1 },
    }

=head4 Output

    {
        type    => 'array',
        element => {
            type => 'hashref',
            keys => {
                type     => { type => 'scalar' },
                severity => { type => 'scalar' },
                message  => { type => 'scalar' },
                fix      => { type => 'scalar', optional => 1 },
            },
        },
    }

=head3 FORMAL SPECIFICATION

    Issue ≔ { type: IssueType, severity: Severity, message: ℤ*, fix?: ℤ* }
    IssueType  â‰” performance | security | cost | maintenance
    Severity   â‰” high | medium | low

    analyze_workflow : Workflow × ℤ* → seq Issue

    âˆ€ w: Workflow, f: ℤ*:
      Â¬has_caching(w)           â‡’ performance∈medium ∈ result(w,f)
      find_unpinned_actions(w)≠∅ ⇒ security∈high     âˆˆ result(w,f)
      find_outdated_actions(w)≠∅ ⇒ maintenance∈medium ∈ result(w,f)
      has_broad_triggers(w)     â‡’ cost∈medium        âˆˆ result(w,f)
      Â¬w.concurrency            â‡’ cost∈low           âˆˆ result(w,f)
      has_outdated_runners(w)   â‡’ maintenance∈low    âˆˆ result(w,f)
      âˆƒ j∈w.jobs: ¬j.timeout-minutes ⇒ performance∈low ∈ result(w,f)

=cut

=head2 get_cache_suggestion($workflow)

Generate a caching suggestion based on detected project type.

=head3 Purpose

Inspect a workflow for known package-manager commands and return a ready-to-paste
C<actions/cache> YAML snippet that matches the detected ecosystem.

=head3 Arguments

=over 4

=item C<$workflow> (HashRef, required)

A parsed workflow hash.  The function inspects each job's C<steps[].run>
commands to detect C<npm>, C<pip>, C<cargo>, or C<bundle>.

=back

=head3 Returns

A non-empty string.  When the ecosystem is recognised the string is an
C<actions/cache> YAML step snippet; otherwise a generic guidance message.

=head3 Side Effects

None.  Pure function.

=head3 Usage Example

    my $suggestion = get_cache_suggestion($workflow);
    say $suggestion;

=head3 API SPECIFICATION

=head4 Input

    { workflow => { type => 'hashref', required => 1 } }

=head4 Output

    { type => 'scalar' }

=head3 FORMAL SPECIFICATION

    Ecosystem ≔ npm | pip | cargo | bundler | unknown

    get_cache_suggestion : Workflow → ℤ*

    ecosystem(w) = npm     â‡’ result contains ~/.npm cache path
    ecosystem(w) = pip     â‡’ result contains ~/.cache/pip path
    ecosystem(w) = cargo   â‡’ result contains ~/.cargo path
    ecosystem(w) = bundler ⇒ result contains vendor/bundle path
    ecosystem(w) = unknown ⇒ result is a generic guidance message

=cut

=head2 find_outdated_actions($workflow)

Return a list of human-readable upgrade notices for any action whose version
string is a key in C<App::GHGen::Fixer::ACTION_UPDATES>.

=head3 Purpose

Detect C<uses:> entries that reference a known-outdated action version.
The detection set is derived directly from C<%ACTION_UPDATES> in
C<App::GHGen::Fixer>, so it is always in sync with what C<update_actions>
can fix: every action flagged here can be auto-fixed, and every action the
Fixer knows about is flagged here.

=head3 Arguments

=over 4

=item C<$workflow> (HashRef, required)

A parsed workflow hash.

=back

=head3 Returns

A list of strings of the form C<"old/action\@vN E<rarr> new/action\@vM">,
one per outdated step found.  Returns an empty list when none are detected.

=head3 Side Effects

None.  Pure function.

=head3 FORMAL SPECIFICATION

    find_outdated_actions : Workflow → seq ℤ*

    outdated ≔ { "$old → $new" ∣ job ∈ w.jobs, step ∈ job.steps,
                  old ∈ dom(%ACTION_UPDATES), step.uses =~ /^\Qold\E/ }
    result ≔ seq(outdated)

=cut

=head1 AUTHOR

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

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

=head1 LICENCE

Copyright 2025-2026 Nigel Horne.

Usage is subject to license terms.

=cut