Make class and enum loader dependency aware

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

Author: MariusStorhaug

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

@@ -1,4 +1,103 @@
-function Add-ContentFromItem {
+function Get-DependencyOrderedScriptFiles {
+    [OutputType([System.IO.FileInfo[]])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [System.IO.FileInfo[]] $Files
+    )
+
+    $sortedFiles = $Files | Sort-Object -Property FullName
+    if ($sortedFiles.Count -le 1) {
+        return $sortedFiles
+    }
+
+    $metadataByPath = @{}
+    $typeToPath = @{}
+    $duplicateTypes = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
+
+    foreach ($file in $sortedFiles) {
+        $content = Get-Content -Path $file.FullName -Raw
+        $declaredTypes = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
+        [Regex]::Matches($content, '(?im)^\s*(class|enum)\s+([^\s:{]+)') | ForEach-Object {
+            [void] $declaredTypes.Add($_.Groups[2].Value)
+        }
+
+        $metadataByPath[$file.FullName] = [pscustomobject]@{
+            File          = $file
+            Content       = $content
+            DeclaredTypes = $declaredTypes
+        }
+
+        foreach ($typeName in $declaredTypes) {
+            if ($typeToPath.ContainsKey($typeName)) {
+                [void]$duplicateTypes.Add($typeName)
+                continue
+            }
+
+            $typeToPath[$typeName] = $file.FullName
+        }
+    }
+
+    $dependenciesByPath = @{}
+    $dependentsByPath = @{}
+    foreach ($file in $sortedFiles) {
+        $dependenciesByPath[$file.FullName] = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
+        $dependentsByPath[$file.FullName] = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
+    }
+
+    foreach ($metadata in $metadataByPath.Values) {
+        foreach ($typeName in $typeToPath.Keys) {
+            if ($duplicateTypes.Contains($typeName)) {
+                continue
+            }
+
+            if ($metadata.DeclaredTypes.Contains($typeName)) {
+                continue
+            }
+
+            $typePattern = "(?<![\w\.])\[$([Regex]::Escape($typeName))\](?![\w\.])"
+            if ([Regex]::IsMatch($metadata.Content, $typePattern, [System.Text.RegularExpressions.RegexOptions]::IgnoreCase)) {
+                $dependencyPath = $typeToPath[$typeName]
+                [void]$dependenciesByPath[$metadata.File.FullName].Add($dependencyPath)
+                [void]$dependentsByPath[$dependencyPath].Add($metadata.File.FullName)
+            }
+        }
+    }
+
+    $remainingPaths = @($sortedFiles.FullName)
+    $ready = @(
+        $remainingPaths |
+        Where-Object { $dependenciesByPath[$_].Count -eq 0 } |
+        Sort-Object
+    )
+    $orderedPaths = [System.Collections.Generic.List[string]]::new()
+
+    while ($ready.Count -gt 0) {
+        $currentPath = $ready[0]
+        $ready = @($ready | Select-Object -Skip 1)
+        $orderedPaths.Add($currentPath)
+        $remainingPaths = @($remainingPaths | Where-Object { $_ -ne $currentPath })
+
+        $dependents = @($dependentsByPath[$currentPath] | Sort-Object)
+        foreach ($dependentPath in $dependents) {
+            $null = $dependenciesByPath[$dependentPath].Remove($currentPath)
+            if ($dependenciesByPath[$dependentPath].Count -eq 0) {
+                $ready = @($ready + $dependentPath | Sort-Object -Unique)
+            }
+        }
+    }
+
+    if ($orderedPaths.Count -lt $sortedFiles.Count) {
+        Write-Warning "Detected cyclical or unresolved class/enum dependencies. Falling back to lexical order for remaining files in [$($sortedFiles[0].DirectoryName)]."
+        $remainingPaths | Sort-Object | ForEach-Object {
+            $orderedPaths.Add($_)
+        }
+    }
+
+    return @($orderedPaths | ForEach-Object { $metadataByPath[$_].File })
+}
+
+function Add-ContentFromItem {
     <#
         .SYNOPSIS
         Add the content of a folder or file to the root module file.
@@ -20,28 +119,34 @@
 
         # The root path of the module.
         [Parameter(Mandatory)]
-        [string] $RootPath
+        [string] $RootPath,
+
+        # Whether the folder should be loaded using dependency ordering (class/enum aware).
+        [Parameter()]
+        [switch] $DependencyAware
     )
-    # Get the path separator for the current OS
-    $pathSeparator = [System.IO.Path]::DirectorySeparatorChar
+    $separators = [char[]]@([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar)
 
-    $relativeFolderPath = $Path -replace $RootPath, ''
-    $relativeFolderPath = $relativeFolderPath -replace $file.Extension, ''
-    $relativeFolderPath = $relativeFolderPath.TrimStart($pathSeparator)
-    $relativeFolderPath = $relativeFolderPath -split $pathSeparator | ForEach-Object { "[$_]" }
+    $relativeFolderPath = [System.IO.Path]::GetRelativePath($RootPath, $Path)
+    $relativeFolderPath = $relativeFolderPath.Split($separators, [System.StringSplitOptions]::RemoveEmptyEntries) | ForEach-Object { "[$_]" }
     $relativeFolderPath = $relativeFolderPath -join ' - '
 
     Add-Content -Path $RootModuleFilePath -Force -Value @"
 #region    $relativeFolderPath
 Write-Debug "[`$scriptName] - $relativeFolderPath - Processing folder"
 "@
 
-    $files = $Path | Get-ChildItem -File -Force -Filter '*.ps1' | Sort-Object -Property FullName
+    if ($DependencyAware) {
+        $files = $Path | Get-ChildItem -Recurse -File -Force -Filter '*.ps1' | Sort-Object -Property FullName
+        $files = Get-DependencyOrderedScriptFiles -Files $files
+    } else {
+        $files = $Path | Get-ChildItem -File -Force -Filter '*.ps1' | Sort-Object -Property FullName
+    }
+
     foreach ($file in $files) {
-        $relativeFilePath = $file.FullName -replace $RootPath, ''
-        $relativeFilePath = $relativeFilePath -replace $file.Extension, ''
-        $relativeFilePath = $relativeFilePath.TrimStart($pathSeparator)
-        $relativeFilePath = $relativeFilePath -split $pathSeparator | ForEach-Object { "[$_]" }
+        $relativeFilePath = [System.IO.Path]::GetRelativePath($RootPath, $file.FullName)
+        $relativeFilePath = [System.IO.Path]::ChangeExtension($relativeFilePath, $null).TrimEnd('.')
+        $relativeFilePath = $relativeFilePath.Split($separators, [System.StringSplitOptions]::RemoveEmptyEntries) | ForEach-Object { "[$_]" }
         $relativeFilePath = $relativeFilePath -join ' - '
 
         Add-Content -Path $RootModuleFilePath -Force -Value @"
@@ -55,9 +160,11 @@ Write-Debug "[`$scriptName] - $relativeFilePath - Done"
 "@
     }
 
-    $subFolders = $Path | Get-ChildItem -Directory -Force | Sort-Object -Property Name
-    foreach ($subFolder in $subFolders) {
-        Add-ContentFromItem -Path $subFolder.FullName -RootModuleFilePath $RootModuleFilePath -RootPath $RootPath
+    if (-not $DependencyAware) {
+        $subFolders = $Path | Get-ChildItem -Directory -Force | Sort-Object -Property Name
+        foreach ($subFolder in $subFolders) {
+            Add-ContentFromItem -Path $subFolder.FullName -RootModuleFilePath $RootModuleFilePath -RootPath $RootPath
+        }
     }
     Add-Content -Path $RootModuleFilePath -Force -Value @"
 Write-Debug "[`$scriptName] - $relativeFolderPath - Done"

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

@@ -10,15 +10,14 @@
 
         1. Module header from header.ps1 file. Usually to suppress code analysis warnings/errors and to add [CmdletBinding()] to the module.
         2. Data loader is added if data files are available.
-        3. Combines *.ps1 files from the following folders in alphabetical order from each folder:
+        3. Combines *.ps1 files from the following folders:
             1. init
-            2. classes/private
-            3. classes/public
-            4. functions/private
-            5. functions/public
-            6. variables/private
-            7. variables/public
-            8. Any remaining *.ps1 on module root.
+            2. classes (dependency-aware ordering for class/enum references)
+            3. functions/private
+            4. functions/public
+            5. variables/private
+            6. variables/public
+            7. Any remaining *.ps1 on module root.
         4. Adds a class loader for classes found in the classes/public folder.
         5. Export-ModuleMember by using the functions, cmdlets, variables and aliases found in the source files.
             - `Functions` will only contain functions that are from the `functions/public` folder.
@@ -48,8 +47,7 @@
         [System.IO.DirectoryInfo] $ModuleOutputFolder
     )
 
-    # Get the path separator for the current OS
-    $pathSeparator = [System.IO.Path]::DirectorySeparatorChar
+    $separators = [char[]]@([System.IO.Path]::DirectorySeparatorChar, [System.IO.Path]::AltDirectorySeparatorChar)
 
     Set-GitHubLogGroup 'Build root module' {
         $rootModuleFile = New-Item -Path $ModuleOutputFolder -Name "$ModuleName.psm1" -Force
@@ -176,31 +174,30 @@ Write-Debug "[$scriptName] - [data] - Done"
         #region - Add content from subfolders
         $scriptFoldersToProcess = @(
             'init',
-            'classes/private',
-            'classes/public',
+            'classes',
             'functions/private',
             'functions/public',
             'variables/private',
             'variables/public'
         )
 
         foreach ($scriptFolder in $scriptFoldersToProcess) {
-            $scriptFolder = Join-Path -Path $ModuleOutputFolder -ChildPath $scriptFolder
-            if (-not (Test-Path -Path $scriptFolder)) {
+            $dependencyAware = $scriptFolder -eq 'classes'
+            $scriptFolderPath = Join-Path -Path $ModuleOutputFolder -ChildPath $scriptFolder
+            if (-not (Test-Path -Path $scriptFolderPath)) {
                 continue
             }
-            Add-ContentFromItem -Path $scriptFolder -RootModuleFilePath $rootModuleFile -RootPath $ModuleOutputFolder
-            Remove-Item -Path $scriptFolder -Force -Recurse
+            Add-ContentFromItem -Path $scriptFolderPath -RootModuleFilePath $rootModuleFile -RootPath $ModuleOutputFolder -DependencyAware:$dependencyAware
+            Remove-Item -Path $scriptFolderPath -Force -Recurse
         }
         #endregion - Add content from subfolders
 
         #region - Add content from *.ps1 files on module root
         $files = $ModuleOutputFolder | Get-ChildItem -File -Force -Filter '*.ps1' | Sort-Object -Property FullName
         foreach ($file in $files) {
-            $relativePath = $file.FullName -replace $ModuleOutputFolder, ''
-            $relativePath = $relativePath -replace $file.Extension, ''
-            $relativePath = $relativePath.TrimStart($pathSeparator)
-            $relativePath = $relativePath -split $pathSeparator | ForEach-Object { "[$_]" }
+            $relativePath = [System.IO.Path]::GetRelativePath($ModuleOutputFolder, $file.FullName)
+            $relativePath = [System.IO.Path]::ChangeExtension($relativePath, $null).TrimEnd('.')
+            $relativePath = $relativePath.Split($separators, [System.StringSplitOptions]::RemoveEmptyEntries) | ForEach-Object { "[$_]" }
             $relativePath = $relativePath -join ' - '
 
             Add-Content -Path $rootModuleFile -Force -Value @"

tests/srcTestRepo/src/classes/public/A-BookList.ps1

@@ -0,0 +1,86 @@
+class BookList {
+    # Static property to hold the list of books
+    static [System.Collections.Generic.List[Book]] $Books
+    # Static method to initialize the list of books. Called in the other
+    # static methods to avoid needing to explicit initialize the value.
+    static [void] Initialize() { [BookList]::Initialize($false) }
+    static [bool] Initialize([bool]$force) {
+        if ([BookList]::Books.Count -gt 0 -and -not $force) {
+            return $false
+        }
+
+        [BookList]::Books = [System.Collections.Generic.List[Book]]::new()
+
+        return $true
+    }
+    # Ensure a book is valid for the list.
+    static [void] Validate([book]$Book) {
+        $Prefix = @(
+            'Book validation failed: Book must be defined with the Title,'
+            'Author, and PublishDate properties, but'
+        ) -join ' '
+        if ($null -eq $Book) { throw "$Prefix was null" }
+        if ([string]::IsNullOrEmpty($Book.Title)) {
+            throw "$Prefix Title wasn't defined"
+        }
+        if ([string]::IsNullOrEmpty($Book.Author)) {
+            throw "$Prefix Author wasn't defined"
+        }
+        if ([datetime]::MinValue -eq $Book.PublishDate) {
+            throw "$Prefix PublishDate wasn't defined"
+        }
+    }
+    # Static methods to manage the list of books.
+    # Add a book if it's not already in the list.
+    static [void] Add([Book]$Book) {
+        [BookList]::Initialize()
+        [BookList]::Validate($Book)
+        if ([BookList]::Books.Contains($Book)) {
+            throw "Book '$Book' already in list"
+        }
+
+        $FindPredicate = {
+            param([Book]$b)
+
+            $b.Title -eq $Book.Title -and
+            $b.Author -eq $Book.Author -and
+            $b.PublishDate -eq $Book.PublishDate
+        }.GetNewClosure()
+        if ([BookList]::Books.Find($FindPredicate)) {
+            throw "Book '$Book' already in list"
+        }
+
+        [BookList]::Books.Add($Book)
+    }
+    # Clear the list of books.
+    static [void] Clear() {
+        [BookList]::Initialize()
+        [BookList]::Books.Clear()
+    }
+    # Find a specific book using a filtering scriptblock.
+    static [Book] Find([scriptblock]$Predicate) {
+        [BookList]::Initialize()
+        return [BookList]::Books.Find($Predicate)
+    }
+    # Find every book matching the filtering scriptblock.
+    static [Book[]] FindAll([scriptblock]$Predicate) {
+        [BookList]::Initialize()
+        return [BookList]::Books.FindAll($Predicate)
+    }
+    # Remove a specific book.
+    static [void] Remove([Book]$Book) {
+        [BookList]::Initialize()
+        [BookList]::Books.Remove($Book)
+    }
+    # Remove a book by property value.
+    static [void] RemoveBy([string]$Property, [string]$Value) {
+        [BookList]::Initialize()
+        $Index = [BookList]::Books.FindIndex({
+                param($b)
+                $b.$Property -eq $Value
+            }.GetNewClosure())
+        if ($Index -ge 0) {
+            [BookList]::Books.RemoveAt($Index)
+        }
+    }
+}