[FEATURE] Investigate low configuration option for change files

Please thumbs up 👍 this issue if this is important to you to help us prioritise this issue.

Your suggestion

PSRule supports processing change files only based on a git diff change set. However, for infrastructure as code that spans multiple files looking a file as changed or not oversimplifies a potentially major infrastructure change.

For example, consider a Bicep module and a deployment parameter file.

In the typical configuration, the module would be excluded from scanning and scanning would occur through the parameter file.

If the Bicep module changes (effectively changing the deployment) but the parameter file does not. The change may be missed by PSRule for processing because git didn't find a change to the parameter file.

The same would apply for ARM template and parameter files, or potentially any other configuration that a whole configuration spans multiple files.

Alternatives

Currently a custom convention can be created to grow the changes set processed by PSRule. This would currently need to be implemented per repository.

For example:

Export-PSRuleConvention 'AddModuleFiles' -Initialize {
    Write-Host "Initializing AddModuleFiles convention"

    # Get the change file set for any bicep files.
    foreach ($inputFile in $PSRule.Repository.GetChangedFiles().WithExtension('.bicep')) {
        # Calculate the module path, modules are expected to be under modules/<moduleName>/v<version>
        # Tests are under modules/<moduleName>/v<version>/.tests/main.tests.bicep
        $modulePath = $inputFile.AsFileInfo().Directory;
        while (!$modulePath.Name.StartsWith('v')) {
            $modulePath = $modulePath.Parent;
        }
        $moduleVersion = $modulePath.Name;
        $moduleName = $modulePath.Parent.Name;

        # Add tests
        Write-Host "Adding module tests for $moduleName/$moduleVersion";

        if (!(Test-Path "$($modulePath.FullName)/.tests/main.tests.bicep")) {
            Write-Warning "No tests found for $moduleName/$moduleVersion";
        }
        else {
            $PSRule.Input.Add($modulePath.FullName + "/.tests/main.tests.bicep");
        }

        # Add matching docs
        $PSRule.Input.Add("docs/modules/$moduleName-$moduleVersion/**");
    }
}

However, this requires customers to configure and maintain additional complexity in each repository.

Some feedback on this includes: https://github.com/microsoft/PSRule/issues/2778#issuecomment-2664999267

Additional context

See #2778

Start by reading the change-file processing behavior and the custom Export-PSRuleConvention example in this issue, then review the feedback in #2778. Define how related files such as Bicep modules and parameter files should be discovered, how configuration should opt into that behavior, and what tests would demonstrate that the complete configuration is processed.