Audits should be able to spot findings based on indirect matrix expansions

[ubiratansoares]

Pre-submission checks

• I am not reporting a bug (crash, false positive/negative, etc). These must be filed via the bug report template.
• I have looked through both the open and closed issues for a duplicate request.
• I affirm that I have followed the AI policy and that this request constitutes my own words and understanding.

What's the problem this feature will solve?

While working with #2350 I took your suggestion, and I had a chance to check matrix.rs, learning about the some opportunities to improve matrix expansions. I'm materializing this issue to back an implementation proposal :)

Some audits that use matrix::Expansions API (crates/zizmor/src/models/workflow/matrix.rs ) may want to know whether the entire matrix is indirectly defined or whether inclusions or exclusions happen via indirection/expressions. These signals could enable audits to report findings based on such indeterminations with the proper confidence / persona (low / pedantic I guess?).

As an example : for zizmor 1.30.0, if one runs the pendantic persona against this Homebrew workflow one will see several unpinned-images errors, but we could also spot something like:

error[unpinned-images]: unpinned image references
   --> path/to/homebrew-core/.github/workflows/tests.yml:365:5
    |
360 |       matrix:
    |       ------ this matrix
361 |         include: ${{fromJson(needs.setup_dep_runners.outputs.runners)}}
    |         --------------------------------------------------------------- values are populated indirectly here
...
365 |     container: ${{matrix.container}}
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ container image may be unpinned
    |
    = note: audit confidence → Low

since the related matrix is fully indirect.

Describe the solution you'd like

matrix::Expansions struct already holds the all walked expansions, but we could also track indetermination sources like

pub(crate) struct Expansions<'doc> {
    /// Consolidated expansions all evaluating inclusions and exclusions
    expansions: Vec<Expansion<'doc>>,

    /// Whether some inclusions are defined by non-static expressions
    /// or even the matrix itself is fully indirect?
    indeterminate_expansions: Option<SymbolicLocation<'doc>>,

    /// Whether some exclusions are defined by non-static expressions
    indeterminate_exclusions: Option<SymbolicLocation<'doc>>,
}

so an audit like unpinned-images can evaluate these signals and spot a pedantic finding out of them.

I already gave a try in the aforementioned idea in a branch I have, which (so far) improves the precision only for unpinned-uses as a proof of concept. It was used the generate the output shared above using a Homebrew repo as a real world example :)

Happy to learn whether this is a design is in the right direction and raise a PR to iterate.

Additional context

This could be also an opportunity to mirror the Github Actions expansions behaviour within matrix.rs, processing exclusions before inclusions. I followed this approach on my branch as well.