Fail build on cyclical class dependencies

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.github/actions/Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1

@@ -39,7 +39,7 @@ Write-Debug "[`$scriptName] - $relativeFolderPath - Processing folder"
 
     if ($DependencyAware) {
         $files = $Path | Get-ChildItem -Recurse -File -Force -Filter '*.ps1' | Sort-Object -Property FullName
-        $files = Get-DependencyOrderedScriptFiles -Files $files
+        $files = Get-DependencyOrderedScriptFile -Files $files
     } else {
         $files = $Path | Get-ChildItem -File -Force -Filter '*.ps1' | Sort-Object -Property FullName
     }

.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1

@@ -187,7 +187,13 @@ Write-Debug "[$scriptName] - [data] - Done"
             if (-not (Test-Path -Path $scriptFolderPath)) {
                 continue
             }
-            Add-ContentFromItem -Path $scriptFolderPath -RootModuleFilePath $rootModuleFile -RootPath $ModuleOutputFolder -DependencyAware:$dependencyAware
+            $addContentParams = @{
+                Path               = $scriptFolderPath
+                RootModuleFilePath = $rootModuleFile
+                RootPath           = $ModuleOutputFolder
+                DependencyAware    = $dependencyAware
+            }
+            Add-ContentFromItem @addContentParams
             Remove-Item -Path $scriptFolderPath -Force -Recurse
         }
         #endregion - Add content from subfolders

…ild/Get-DependencyOrderedScriptFiles.ps1 …uild/Get-DependencyOrderedScriptFile.ps1.github/actions/Build-PSModule/src/helpers/Build/Get-DependencyOrderedScriptFiles.ps1 renamed to .github/actions/Build-PSModule/src/helpers/Build/Get-DependencyOrderedScriptFile.ps1 .github/actions/Build-PSModule/src/helpers/Build/Get-DependencyOrderedScriptFiles.ps1 renamed to .github/actions/Build-PSModule/src/helpers/Build/Get-DependencyOrderedScriptFile.ps1

@@ -1,12 +1,24 @@
-function Get-DependencyOrderedScriptFiles {
+function Get-DependencyOrderedScriptFile {
+    <#
+        .SYNOPSIS
+        Sorts script files so class/enum dependencies are loaded before dependents.
+
+        .DESCRIPTION
+        Reads declared class/enum types and type references from each script and returns
+        files in dependency order. When a cyclical dependency is detected, the function
+        warns and throws to fail the build early.
+
+        .EXAMPLE
+        Get-DependencyOrderedScriptFile -Files (Get-ChildItem -Path '.\classes' -Filter '*.ps1')
+    #>
     [OutputType([System.IO.FileInfo[]])]
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
         [System.IO.FileInfo[]] $Files
     )
 
-    $sortedFiles = $Files | Sort-Object -Property FullName
+    [System.IO.FileInfo[]]$sortedFiles = $Files | Sort-Object -Property FullName
     if ($sortedFiles.Count -le 1) {
         return $sortedFiles
     }
@@ -67,8 +79,8 @@ function Get-DependencyOrderedScriptFiles {
     $remainingPaths = @($sortedFiles.FullName)
     $ready = @(
         $remainingPaths |
-        Where-Object { $dependenciesByPath[$_].Count -eq 0 } |
-        Sort-Object
+            Where-Object { $dependenciesByPath[$_].Count -eq 0 } |
+            Sort-Object
     )
     $orderedPaths = [System.Collections.Generic.List[string]]::new()
 
@@ -89,11 +101,13 @@ function Get-DependencyOrderedScriptFiles {
 
     if ($orderedPaths.Count -lt $sortedFiles.Count) {
         $remainingNames = ($remainingPaths | ForEach-Object { [System.IO.Path]::GetFileName($_) }) -join ', '
-        Write-Warning "Cyclical class/enum dependencies detected in [$($sortedFiles[0].DirectoryName)]. Falling back to lexical order for unresolved files: $remainingNames"
-        $remainingPaths | Sort-Object | ForEach-Object {
-            $orderedPaths.Add($_)
-        }
+        $message = @(
+            "Cyclical class/enum dependencies detected in [$($sortedFiles[0].DirectoryName)]."
+            "Build cannot continue with unresolved files: $remainingNames"
+        ) -join ' '
+        Write-Warning $message
+        throw $message
     }
 
-    return @($orderedPaths | ForEach-Object { $metadataByPath[$_].File })
+    return [System.IO.FileInfo[]]@($orderedPaths | ForEach-Object { $metadataByPath[$_].File })
 }