Enhance performance and documentation for DSC resource integration tests (#2141)

Author: johlju

.build/README.md

@@ -16,8 +16,10 @@ resources and classes, then checks if any relevant files have been modified.
 
 ### How It Works
 
-The script checks for changes to:
+The script performs an optimized analysis by checking for changes in this order:
 
+1. **Early Source Check**: First checks if any files under `source/` have changed
+   - If no source changes, skips integration tests immediately
 1. **DSC Resources**: Files under `source/DSCResources/`
 1. **Classes**: Files under `source/Classes/`
 1. **Public Commands**: Commands that are actually used by DSC resources or
@@ -27,6 +29,47 @@ The script checks for changes to:
 1. **Integration Tests**: DSC resource integration test files under
    `tests/Integration/Resources/`
 
+### Flow Diagram
+
+The following diagram illustrates the decision flow of the script:
+
+<!-- markdownlint-disable MD013 - Mermaid diagram has long lines -->
+```mermaid
+flowchart TD
+    Start([Start Script]) --> Init[Initialize Parameters<br/>BaseBranch, CurrentBranch, UseMergeBase]
+    Init --> GetChanges[Get Changed Files<br/>git diff between branches]
+
+    GetChanges --> HasChanges{Any Changed<br/>Files?}
+    HasChanges -->|No| RunTrue[Return TRUE<br/>Run integration tests]
+
+    HasChanges -->|Yes| CheckSource{Any Changes<br/>Under source/?}
+    CheckSource -->|No| Skip[Return FALSE<br/>Skip integration tests]
+
+    CheckSource -->|Yes| Discover[Discover Public Commands<br/>Used by DSC Resources]
+    Discover --> CheckDscRes{DSC Resources or<br/>Classes Changed?<br/>source/DSCResources/<br/>source/Classes/}
+    CheckDscRes -->|Yes| RunTrue
+
+    CheckDscRes -->|No| CheckPublic{Public Commands<br/>Used by DSC<br/>Resources Changed?<br/>source/Public/}
+    CheckPublic -->|Yes| RunTrue
+
+    CheckPublic -->|No| CheckPrivate{Private Functions<br/>Used by DSC-related<br/>Commands Changed?<br/>source/Private/}
+    CheckPrivate -->|Yes| RunTrue
+
+    CheckPrivate -->|No| CheckTests{Integration Test<br/>Files Changed?<br/>tests/Integration/Resources/}
+    CheckTests -->|Yes| RunTrue
+
+    CheckTests -->|No| Skip
+
+    RunTrue --> End([End])
+    Skip --> End
+
+    style Start fill:#e1f5fe
+    style End fill:#e8f5e8
+    style RunTrue fill:#fff3e0
+    style Skip fill:#f3e5f5
+```
+<!-- markdownlint-enable MD013 -->
+
 ### Parameters
 
 | Parameter | Type | Default | Purpose |

.build/Test-ShouldRunDscResourceIntegrationTests.ps1

@@ -380,10 +380,12 @@ function Get-PrivateFunctionsUsedByClassResources
     .DESCRIPTION
         This function analyzes the changes between two git references and determines
         if DSC resource integration tests should run based on the files that have
-        been modified. It checks for changes to DSC resources, classes, public
-        commands used by DSC resources, private functions used by those public commands,
-        private functions used by class-based DSC resources, and integration
-        tests.
+        been modified. It performs an optimized analysis by first checking if any
+        changes exist under the source/ folder. If no source changes are detected,
+        it skips the expensive analysis and returns false. Otherwise, it checks for
+        changes to DSC resources, classes, public commands used by DSC resources,
+        private functions used by those public commands, private functions used by
+        class-based DSC resources, and integration tests.
     .PARAMETER BaseBranch
         The base branch to compare against. Default is 'origin/main'.
 
@@ -443,11 +445,6 @@ function Test-ShouldRunDscResourceIntegrationTests
     }
     Write-Host ""
 
-    # Get list of public commands used by DSC resources dynamically
-    $PublicCommandsUsedByDscResources = Get-PublicCommandsUsedByDscResources -SourcePath $SourcePath
-    Write-Host "Discovered $($PublicCommandsUsedByDscResources.Count) public commands used by DSC resources and classes."
-    Write-Host ""
-
     $changedFiles = Get-ChangedFiles -From $BaseBranch -To $CurrentBranch -UseMergeBase:$UseMergeBase
 
     if (-not $changedFiles)
@@ -462,6 +459,20 @@ function Test-ShouldRunDscResourceIntegrationTests
     Write-Host "##[endgroup]"
     Write-Host ""
 
+    # Early optimization: Check if any changes are under the source folder
+    $changedSourceFiles = $changedFiles | Where-Object -FilterScript { $_ -match '^source/' }
+    if (-not $changedSourceFiles)
+    {
+        Write-Host "No changes detected under the source folder. DSC resource integration tests can be skipped."
+        Write-Host ""
+        return $false
+    }
+
+    # Get list of public commands used by DSC resources dynamically (only when needed)
+    $PublicCommandsUsedByDscResources = Get-PublicCommandsUsedByDscResources -SourcePath $SourcePath
+    Write-Host "Discovered $($PublicCommandsUsedByDscResources.Count) public commands used by DSC resources and classes."
+    Write-Host ""
+
     # Check if any DSC resources are directly changed
     $changedDscResources = $changedFiles | Where-Object -FilterScript { $_ -match '^source/DSCResources/' -or $_ -match '^source/Classes/' }
     if ($changedDscResources)

.github/instructions/dsc-community-style-guidelines.instructions.md

@@ -23,6 +23,7 @@ applyTo: "**"
 - Integration tests: `tests/Integration/Commands/{CommandName}.Integration.Tests.ps1`
 
 ## Requirements
+- Follow guidelines over existing code patterns
 - Always update CHANGELOG.md Unreleased section
 - Localize all strings using string keys
 - Check DscResource.Common before creating private functions

CHANGELOG.md

@@ -78,6 +78,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     resources, public commands used by resources, or related components.
   - Unit tests, QA tests, and command integration tests continue to run for
     all changes.
+- `.build/Test-ShouldRunDscResourceIntegrationTests.ps1`
+  - Improved performance by adding early optimization to check for changes
+    under source folder before expensive analysis.
+  - Moved public command discovery to only run when source changes are detected.
+- `.build/README.md`
+  - Added flow diagram showing decision process for DSC resource integration tests.
+  - Improved documentation with optimized analysis workflow description.
+- DSC community style guidelines
+  - Added requirement to follow guidelines over existing code patterns.
 
 ## [17.1.0] - 2025-05-22