Merge branch 'main' into copilot/fix-431868db-717c-46b0-9850-6caf1fb09dd8

Author: johlju

.build/README.md

@@ -1,19 +1,26 @@
-# DSC Resource Integration Test Optimization
+# .build scripts
 
-This document describes the script used to dynamically determine whether DSC
-resource integration tests should run in Azure Pipelines.
+Documentation for the SqlServerDsc module build and pipeline scripts.
 
-## What the Script Does
+## `Test-ShouldRunDscResourceIntegrationTests.ps1`
 
-The `Test-ShouldRunDscResourceIntegrationTests.ps1` script analyzes git
+This script dynamically determines whether DSC resource integration tests
+should run in Azure Pipelines.
+
+### What the Script Does
+<!-- markdownlint-disable-next-line MD013 -->
+The [`Test-ShouldRunDscResourceIntegrationTests.ps1`](./Test-ShouldRunDscResourceIntegrationTests.ps1) script analyzes git
 changes between two references and determines if DSC resource integration tests
 need to run. It automatically discovers which public commands are used by DSC
 resources and classes, then checks if any relevant files have been modified.
 
-## How It Works
+### 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 the configured
+   source path (`-SourcePath`, default `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
@@ -23,26 +30,94 @@ The script checks for changes to:
 1. **Integration Tests**: DSC resource integration test files under
    `tests/Integration/Resources/`
 
-## Usage
+### 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 SourcePath?}
+    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
 
-### Azure Pipelines
+    style Start fill:#e1f5fe
+    style End fill:#e8f5e8
+    style RunTrue fill:#fff3e0
+    style Skip fill:#f3e5f5
+```
+<!-- markdownlint-enable MD013 -->
+
+### Parameters
+
+| Parameter | Type | Default | Purpose |
+|-----------|------|---------|---------|
+| `BaseBranch` | String | `'origin/main'` | Base branch to compare against |
+| `CurrentBranch` | String | `'HEAD'` | Current branch or commit to compare |
+| `UseMergeBase` | Switch | `$false` | Use merge-base to compute diff base |
+
+### Outputs
+
+<!-- markdownlint-disable MD013 - Table with long descriptions -->
+| Output | Type | Description |
+|--------|------|-------------|
+| Return value | Boolean | `$true` when the monitored categories have relevant changes between the specified refs, `$false` when no such changes are detected |
+<!-- markdownlint-enable MD013 -->
+
+### Usage
+
+#### Azure Pipelines
 
 The Azure Pipelines task sets an output variable that downstream stages can
 use to conditionally run DSC resource integration tests. The script returns
 a boolean value that the pipeline captures, e.g.:
 
+<!-- markdownlint-disable MD013 -->
 ```yaml
 - powershell: |
-    $shouldRun = ./.build/Test-ShouldRunDscResourceIntegrationTests.ps1 -BaseBranch $targetBranch -CurrentBranch HEAD
+    $shouldRun = & ./.build/Test-ShouldRunDscResourceIntegrationTests.ps1 -BaseBranch $targetBranch -CurrentBranch HEAD -UseMergeBase
     Write-Host "##vso[task.setvariable variable=ShouldRunDscResourceIntegrationTests;isOutput=true]$shouldRun"
   displayName: 'Determine if DSC resource tests should run'
+  name: determineShouldRun
 ```
+<!-- markdownlint-enable MD013 -->
 
-Downstream stages reference this output variable using the pattern:
-`dependencies.JobName.outputs['StepName.VariableName']` to gate their
-execution based on whether DSC resource tests should run.
+Downstream stages reference this output variable in a stage `condition:`
+using the pattern:
+<!-- markdownlint-disable MD013 -->
+```yaml
+condition: |
+and(
+   succeeded(),
+   eq(lower(dependencies.stageName.outputs['jobName.taskName.ShouldRunDscResourceIntegrationTests']), 'true')
+)
+```
+<!-- markdownlint-enable MD013 -->
 
-### Command Line
+#### Command Line
 
 ```powershell
 # Basic usage (compares current HEAD with origin/main)
@@ -52,9 +127,3 @@ execution based on whether DSC resource tests should run.
 .build/Test-ShouldRunDscResourceIntegrationTests.ps1 -BaseBranch 'origin/dev' \
     -CurrentBranch 'feature-branch'
 ```
-
-## Dynamic Discovery
-
-The script automatically discovers public commands used by DSC resources by
-scanning source files, eliminating the need to maintain hardcoded lists.
-This ensures accuracy and reduces maintenance overhead.

.build/Test-ShouldRunDscResourceIntegrationTests.ps1

@@ -17,12 +17,20 @@
     .PARAMETER CurrentBranch
         The current branch or commit to compare. Default is 'HEAD'.
 
+    .PARAMETER UseMergeBase
+        When specified, compares the current branch against the merge-base with the base branch
+        instead of directly comparing against the base branch. This is useful for comparing
+        only the changes introduced by the current branch.
+
     .EXAMPLE
         Test-ShouldRunDscResourceIntegrationTests
 
     .EXAMPLE
         Test-ShouldRunDscResourceIntegrationTests -BaseBranch 'origin/main' -CurrentBranch 'HEAD'
 
+    .EXAMPLE
+        Test-ShouldRunDscResourceIntegrationTests -BaseBranch 'origin/main' -CurrentBranch 'HEAD' -UseMergeBase
+
     .OUTPUTS
         System.Boolean. Returns $true if DSC resource integration tests should run, $false otherwise.
 #>
@@ -35,7 +43,11 @@ param
 
     [Parameter()]
     [System.String]
-    $CurrentBranch = 'HEAD'
+    $CurrentBranch = 'HEAD',
+
+    [Parameter()]
+    [System.Management.Automation.SwitchParameter]
+    $UseMergeBase
 )
 
 <#
@@ -137,17 +149,25 @@ function Get-PublicCommandsUsedByDscResources
     .DESCRIPTION
         This function retrieves the list of files that have been modified between
         two git references using git diff. It handles various scenarios including
-        different diff syntax and untracked files.
+        different diff syntax and untracked files. Optionally can compare against
+        the merge-base of the two references.
 
     .PARAMETER From
         The source git reference (branch, commit, tag).
 
     .PARAMETER To
         The target git reference (branch, commit, tag).
 
+    .PARAMETER UseMergeBase
+        When specified, finds the merge-base between From and To references and
+        compares To against that merge-base instead of directly against From.
+
     .EXAMPLE
         Get-ChangedFiles -From 'origin/main' -To 'HEAD'
 
+    .EXAMPLE
+        Get-ChangedFiles -From 'origin/main' -To 'HEAD' -UseMergeBase
+
     .OUTPUTS
         System.String[]. Array of file paths that have been changed.
 #>
@@ -162,23 +182,46 @@ function Get-ChangedFiles
 
         [Parameter(Mandatory = $true)]
         [System.String]
-        $To
+        $To,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $UseMergeBase
     )
 
     try
     {
+        $compareFrom = $From
+
+        # If UseMergeBase is specified, find the merge-base between From and To
+        if ($UseMergeBase)
+        {
+            Write-Verbose "Finding merge-base between $From and $To"
+            $mergeBase = & git merge-base $From $To 2>&1
+            if ($LASTEXITCODE -eq 0 -and $mergeBase)
+            {
+                $compareFrom = $mergeBase.Trim()
+                Write-Verbose "Using merge-base: $compareFrom"
+            }
+            else
+            {
+                Write-Warning "Failed to find merge-base between $From and $To. Falling back to direct comparison. Exit code: $LASTEXITCODE. Output: $mergeBase"
+                $compareFrom = $From
+            }
+        }
+
         # Try different git diff approaches
         $gitDiffOutput = $null
 
         # First, try the standard diff
-        $gitDiffOutput = & git diff --name-only "$From..$To" 2>&1
+        $gitDiffOutput = & git diff --name-only "$compareFrom..$To" 2>&1
         if ($LASTEXITCODE -eq 0 -and $gitDiffOutput)
         {
             return $gitDiffOutput | Where-Object -FilterScript { $_ -and $_.Trim() }
         }
 
         # If that fails, try without the range syntax
-        $gitDiffOutput = & git diff --name-only $From $To 2>&1
+        $gitDiffOutput = & git diff --name-only $compareFrom $To 2>&1
         if ($LASTEXITCODE -eq 0 -and $gitDiffOutput)
         {
             return $gitDiffOutput | Where-Object -FilterScript { $_ -and $_.Trim() }
@@ -194,7 +237,7 @@ function Get-ChangedFiles
             }
         }
 
-        Write-Warning "Failed to get git diff between $From and $To. Exit code: $LASTEXITCODE. Output: $gitDiffOutput"
+        Write-Warning "Failed to get git diff between $compareFrom and $To. Exit code: $LASTEXITCODE. Output: $gitDiffOutput"
         return @()
     }
     catch
@@ -337,16 +380,23 @@ 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'.
 
     .PARAMETER CurrentBranch
         The current branch or commit to compare. Default is 'HEAD'.
 
+    .PARAMETER UseMergeBase
+        When specified, compares the current branch against the merge-base with the base branch
+        instead of directly comparing against the base branch. This is useful for comparing
+        only the changes introduced by the current branch.
+
     .PARAMETER SourcePath
         The source path containing the source code directories. Default is 'source'.
 
@@ -356,6 +406,9 @@ function Get-PrivateFunctionsUsedByClassResources
     .EXAMPLE
         Test-ShouldRunDscResourceIntegrationTests -BaseBranch 'origin/main' -CurrentBranch 'feature-branch'
 
+    .EXAMPLE
+        Test-ShouldRunDscResourceIntegrationTests -BaseBranch 'origin/main' -CurrentBranch 'feature-branch' -UseMergeBase
+
     .OUTPUTS
         System.Boolean. Returns $true if DSC resource integration tests should run, $false otherwise.
 #>
@@ -372,21 +425,27 @@ function Test-ShouldRunDscResourceIntegrationTests
         [System.String]
         $CurrentBranch = 'HEAD',
 
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $UseMergeBase,
+
         [Parameter()]
         [System.String]
         $SourcePath = 'source'
     )
 
     Write-Host "##[section]Analyzing DSC Resource Integration Test Requirements"
-    Write-Host "Analyzing changes between $BaseBranch and $CurrentBranch..."
-    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."
+    if ($UseMergeBase)
+    {
+        Write-Host "Analyzing changes introduced by $CurrentBranch since merge-base with $BaseBranch..."
+    }
+    else
+    {
+        Write-Host "Analyzing changes between $BaseBranch and $CurrentBranch..."
+    }
     Write-Host ""
 
-    $changedFiles = Get-ChangedFiles -From $BaseBranch -To $CurrentBranch
+    $changedFiles = Get-ChangedFiles -From $BaseBranch -To $CurrentBranch -UseMergeBase:$UseMergeBase
 
     if (-not $changedFiles)
     {
@@ -400,6 +459,21 @@ function Test-ShouldRunDscResourceIntegrationTests
     Write-Host "##[endgroup]"
     Write-Host ""
 
+    # Early optimization: Check if any changes are under the source folder
+    $sourcePrefix = '^' + [regex]::Escape((($SourcePath -replace '\\','/') -replace '/+$','')) + '/'
+    $changedSourceFiles = $changedFiles | Where-Object -FilterScript { $_ -match $sourcePrefix }
+    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)
@@ -413,7 +487,7 @@ function Test-ShouldRunDscResourceIntegrationTests
     }
 
     # Check if any public commands used by DSC resources are changed
-    $changedPublicCommands = $changedFiles | Where-Object -FilterScript { $_ -match '^source/Public/(.+)\.ps1$' } | 
+    $changedPublicCommands = $changedFiles | Where-Object -FilterScript { $_ -match '^source/Public/(.+)\.ps1$' } |
         ForEach-Object -Process { [System.IO.Path]::GetFileNameWithoutExtension((Split-Path -Path $_ -Leaf)) }
 
     $affectedCommands = $changedPublicCommands | Where-Object -FilterScript { $_ -in $PublicCommandsUsedByDscResources }
@@ -428,7 +502,7 @@ function Test-ShouldRunDscResourceIntegrationTests
     }
 
     # Check if any private functions used by the affected public commands or class-based DSC resources are changed
-    $changedPrivateFunctions = $changedFiles | Where-Object -FilterScript { $_ -match '^source/Private/(.+)\.ps1$' } | 
+    $changedPrivateFunctions = $changedFiles | Where-Object -FilterScript { $_ -match '^source/Private/(.+)\.ps1$' } |
         ForEach-Object -Process { [System.IO.Path]::GetFileNameWithoutExtension((Split-Path -Path $_ -Leaf)) }
 
     $affectedPrivateFunctions = @()
@@ -477,7 +551,7 @@ function Test-ShouldRunDscResourceIntegrationTests
 # If script is run directly (not imported), execute the main function
 if ($MyInvocation.InvocationName -ne '.')
 {
-    $shouldRun = Test-ShouldRunDscResourceIntegrationTests -BaseBranch $BaseBranch -CurrentBranch $CurrentBranch
+    $shouldRun = Test-ShouldRunDscResourceIntegrationTests -BaseBranch $BaseBranch -CurrentBranch $CurrentBranch -UseMergeBase:$UseMergeBase
 
     # Provide clear final result with appropriate color coding
     Write-Host "##[section]Test Requirements Decision"
@@ -490,10 +564,6 @@ if ($MyInvocation.InvocationName -ne '.')
         Write-Host "RESULT: DSC resource integration tests will be SKIPPED"
     }
 
-    # Output the result for the calling script to capture
-    Write-Output -InputObject ""
-    Write-Output -InputObject "ShouldRunDscResourceIntegrationTests: $shouldRun"
-
     # Return the boolean value for pipeline script to use
     return $shouldRun
 }