🩹 [Patch]: Don't require the source code to be in a folder with name …

…of module (#44) ## Description - Don't require the source code to be in a folder with name of module - Fixes #43 ## Type of change  - [ ] 📖 [Docs] - [ ] 🪲 [Fix] - [x] 🩹 [Patch] - [ ] ⚠️ [Security fix] - [ ] 🚀 [Feature] - [ ] 🌟 [Breaking change] ## Checklist  - [x] I have performed a self-review of my own code - [x] I have commented my code, particularly in hard-to-understand areas
PSModule · Mar 29, 2024 · 31b5bd5 · 31b5bd5
1 parent 613e59c
commit 31b5bd5
Show file tree

Hide file tree

Showing 27 changed files with 77 additions and 192 deletions.
diff --git a/README.md b/README.md
@@ -33,41 +33,42 @@ During the build process the following steps are performed:
 
 ## Root module
 
+The `src` folder may contain a 'root module' file. If present, the build function will disregard this file
+and build a new root module file based on the source code in the module folder.
+
 The root module file is the main file that is loaded when the module is imported.
 It is built from the source code files in the module folder in the following order:
 
-1. Adds module headers from `header.ps1`.
+1. Adds module headers from `header.ps1` if it exists and removes the file from the module folder.
 1. Adds data loader automation that loads files from the `data` folder as variables in the module scope, if it exists. The variables are available using the ´$script:<filename>´ syntax.
-1. Adds content from subfolders, in the order:
-   - Init
-   - Private
-   - Public
-   - *.ps1 on module root
-1. Adds the Export-ModuleMember function to the end of the file, to make sure that only the functions, cmdlets, variables and aliases that are defined in the module are exported.
-
-### The root module in the `src` folder
-
-The root module file that is included in the source files contains the same functionality but is not optimized for performance.
-The goal with this is to have a quick way to import and test the module without having to build it.
+1. Adds content from subfolders, if they exists, and removes them from the module folder in the following order:
+   - `init`
+   - `classes`
+   - `private`
+   - `public`
+   - `*.ps1` on module root
+1. Adds a `class` and `enum` exporter that exports all classes and enums in the module to the caller session, using TypeAccelerators.
+1. Adds the `Export-ModuleMember` function to the end of the file, to make sure that only the functions, cmdlets, variables and aliases that are defined in the module are exported.
 
 ## Module manifest
 
 The module manifest file is the file that describes the module and its content. It is used by PowerShell to load the module and its prerequisites.
-The file also contains important metadata that is used by the PowerShell Gallery.
+The file also contains important metadata that is used by the PowerShell Gallery. If a file exists in the source code folder `src` it will be used as a base for the module manifest file.
+Most of the values in the module manifest file are calculated during the build process however some of these will not be touched if specified in the source manifest file.
 
 During the module manifest build process the following steps are performed:
 
-1. Get the manifest file from the source code. Content from this file overrides any value that would be calculated based on the source code.
-1. Find and set the `RootModule` based on filename and extension.
+1. Get the manifest file from the source code. If it does not exist, a new manifest file is created.
+1. Generate and set the `RootModule` based module name.
 1. Set a temporary `ModuleVersion`, as this is set during the release process by [Publish-PSModule](https://github.com/PSModule/Publish-PSModule).
-1. Set the `Author` and `CompanyName` based on GitHub Owner.
-1. Set the `Copyright` information based on a default text (`(c) 2024 >>OwnerName<<. All rights reserved.`) and adds either the `Author`, `CompanyName` or both (`Author | CompanyName`) when these are different.
-1. Set the `Description` based on the GitHub repository description.
-1. Set various properties in the manifest such as `PowerShellHostName`, `PowerShellHostVersion`, `DotNetFrameworkVersion`, `ClrVersion`, and `ProcessorArchitecture`. There is currently no automation for these properties.
+1. Set the `Author` and `CompanyName` based on GitHub Owner. If a value exists in the source manifest file, this value is used.
+1. Set the `Copyright` information based on a default text (`(c) 2024 >>OwnerName<<. All rights reserved.`) and adds either the `Author`, `CompanyName` or both (`Author | CompanyName`) when these are different. If a value exists in the source manifest file, this value is used.
+1. Set the `Description` based on the GitHub repository description. If a value exists in the source manifest file, this value is used.
+1. Set various properties in the manifest such as `PowerShellHostName`, `PowerShellHostVersion`, `DotNetFrameworkVersion`, `ClrVersion`, and `ProcessorArchitecture`. There is currently no automation for these properties. If a value exists in the source manifest file, this value is used.
 1. Get the list of files in the module source folder and set the `FileList` property in the manifest.
 1. Get the list of required assemblies (`*.dll` files) from the `assemblies` folder and set the `RequiredAssemblies` property in the manifest.
 1. Get the list of nested modules (`*.psm1` files) from the `modules` folder and set the `NestedModules` property in the manifest.
-1. Get the list of scripts to process (`*.ps1` files) from the `classes` and `scripts` folders and set the `ScriptsToProcess` property in the manifest. This ensures that the scripts are loaded to the caller session (parent of module session).
+1. Get the list of scripts to process (`*.ps1` files) from the `scripts` folders and set the `ScriptsToProcess` property in the manifest. This ensures that the scripts are loaded to the caller session (parent of module session).
 1. Get the list of types to process by searching for `*.Types.ps1xml` files in the entire module source folder and set the `TypesToProcess` property in the manifest.
 1. Get the list of formats to process by searching for `*.Format.ps1xml` files in the entire module source folder and set the `FormatsToProcess` property in the manifest.
 1. Get the list of DSC resources to export by searching for `*.psm1` files in the `resources` folder and set the `DscResourcesToExport` property in the manifest.
@@ -76,22 +77,22 @@ During the module manifest build process the following steps are performed:
 1. Gather information from source files to update `RequiredModules`, `PowerShellVersion`, and `CompatiblePSEditions` properties.
 1. The following values are gathered from the GitHub repository:
    - `Tags` are generated from Repository topics in addition to compatability tags gathered from the source code.
-   - `LicenseUri` is generated assuming there is a `LICENSE` file on the root of the repository.
-   - `ProjectUri` is the URL to the GitHub repository
-   - `IconUri` is generated assuming there is a `icon.png` file in the `icon` folder on the repository root.
+   - `LicenseUri` is generated assuming there is a `LICENSE` file on the root of the repository. If a value exists in the source manifest file, this value is used.
+   - `ProjectUri` is the URL to the GitHub repository. If a value exists in the source manifest file, this value is used.
+   - `IconUri` is generated assuming there is a `icon.png` file in the `icon` folder on the repository root. If a value exists in the source manifest file, this value is used.
 1. `ReleaseNotes` currently not automated, but could be the PR description or release description.
 1. `PreRelease` is not managed here, but is managed from [Publish-PSModule](https://github.com/PSModule/Publish-PSModule)
-1. `RequireLicenseAcceptance` is not automated and defaults to `false`, and
-1. `ExternalModuleDependencies` is currenlty not automated.
-1. `HelpInfoURI` is not automated.
+1. `RequireLicenseAcceptance` is not automated and defaults to `false`. If a value exists in the source manifest file, this value is used.
+1. `ExternalModuleDependencies` is currenlty not automated. If a value exists in the source manifest file, this value is used.
+1. `HelpInfoURI` is not automated. If a value exists in the source manifest file, this value is used.
 1. Create a new manifest file in the output folder with the gathered info above. This also generates a new `GUID` for the module.
 1. Format the manifest file using the `Set-ModuleManifest` function from the [Utilities](https://github.com/PSModule/Utilities) module.
 
 Linking the description to the module manifest file might show more how this works:
 
 ```powershell
 @{
-    RootModule             = 'Utilities.psm1' # Get files from root of folder wher name is same as the folder and file extension is .psm1, .ps1, .psd1, .dll, .cdxml, .xaml. Error if there are multiple files that meet the criteria.
+    RootModule             = 'Utilities.psm1' # Generated from the module name, <moduleName>.psm1
     ModuleVersion          = '0.0.1' # Set during release using Publish-PSModule.
     CompatiblePSEditions   = @() # Get from source files, REQUIRES -PSEdition <PSEdition-Name>, null if not provided.
     GUID                   = '<GUID>' # Generated when finally saving the manifest using New-ModuleManifest.
@@ -142,16 +143,9 @@ Linking the description to the module manifest file might show more how this wor
 }
 ```
 
-### The module manifest in the `src` folder
-
-The module manifest file that is included in the source files contains the same functionality but is not optimized for performance and does not automatically gather all the information that is gathered during the build process.
-The goal with this is to have a quick way to import and test the module without having to build it.
-
-The source module manifest is also the only place where some of the values can be controlled. These values are typically difficult to calculate and are not automated.
-
 ## Module documentation
 
-The module documentation is built using platyPS and comment based help in the source code.
+The module documentation is built using `platyPS` and comment based help in the source code.
 The documentation is currently not published anywhere, but should be published to GitHub Pages in a future release.
 
 ## Permissions

diff --git a/scripts/helpers/Build-PSModule.ps1 b/scripts/helpers/Build-PSModule.ps1
@@ -10,6 +10,10 @@ function Build-PSModule {
     #>
     [CmdletBinding()]
     param(
+        # Name of the module.
+        [Parameter(Mandatory)]
+        [string] $ModuleName,
+
         # Path to the folder where the modules are located.
         [Parameter(Mandatory)]
         [string] $ModuleSourceFolderPath,
@@ -23,20 +27,18 @@ function Build-PSModule {
         [string] $DocsOutputFolderPath
     )
 
-    $moduleName = Split-Path -Path $ModuleSourceFolderPath -Leaf
-
-    Start-LogGroup "Building module [$moduleName]"
+    Start-LogGroup "Building module [$ModuleName]"
     Write-Verbose "Source path:          [$ModuleSourceFolderPath]"
     if (-not (Test-Path -Path $ModuleSourceFolderPath)) {
         Write-Error "Source folder not found at [$ModuleSourceFolderPath]"
         exit 1
     }
     $moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath
 
-    $moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $moduleName -ItemType Directory -Force
+    $moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force
     Write-Verbose "Module output folder: [$ModulesOutputFolderPath]"
 
-    $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -Name $moduleName -ItemType Directory -Force
+    $docsOutputFolder = New-Item -Path $DocsOutputFolderPath -Name $ModuleName -ItemType Directory -Force
     Write-Verbose "Docs output folder:   [$DocsOutputFolderPath]"
     Stop-LogGroup
 

diff --git a/scripts/helpers/Build/Build-PSModuleManifest.ps1 b/scripts/helpers/Build/Build-PSModuleManifest.ps1
@@ -26,14 +26,17 @@ function Build-PSModuleManifest {
     #region Build manifest file
     Start-LogGroup 'Build manifest file'
     $moduleName = Split-Path -Path $ModuleOutputFolder -Leaf
-    $manifestFileName = "$moduleName.psd1"
-    $manifestOutputPath = Join-Path -Path $ModuleOutputFolder -ChildPath $manifestFileName
-    $manifestFile = Get-Item -Path $manifestOutputPath
-    Write-Verbose ($manifestFile | Format-List | Out-String)
-    $manifest = Get-ModuleManifest -Path $manifestFile -Verbose:$false
-
-    $rootModule = Get-PSModuleRootModule -SourceFolderPath $ModuleOutputFolder
-    $manifest.RootModule = $rootModule
+    $sourceManifestFilePath = Join-Path -Path $ModuleOutputFolder -ChildPath "$moduleName.psd1"
+    if (-not (Test-Path -Path $sourceManifestFilePath)) {
+        $sourceManifestFilePath = Join-Path -Path $ModuleOutputFolder -ChildPath 'manifest.psd1'
+    }
+    $manifest = if (-not (Test-Path -Path $sourceManifestFilePath)) {
+        @{}
+    } else {
+        Get-ModuleManifest -Path $sourceManifestFilePath -Verbose:$false
+    }
+
+    $manifest.RootModule = "$moduleName.psm1"
     $manifest.ModuleVersion = '999.0.0'
 
     $manifest.Author = $manifest.Keys -contains 'Author' ? ($manifest.Author | IsNotNullOrEmpty) ? $manifest.Author : $env:GITHUB_REPOSITORY_OWNER : $env:GITHUB_REPOSITORY_OWNER
@@ -71,10 +74,19 @@ function Build-PSModuleManifest {
     $pathSeparator = [System.IO.Path]::DirectorySeparatorChar
 
     Write-Verbose '[FileList]'
-    $files = $ModuleOutputFolder | Get-ChildItem -File -ErrorAction SilentlyContinue | Where-Object -Property Name -NotLike '*.ps1'
-    $files += $ModuleOutputFolder | Get-ChildItem -Directory | Get-ChildItem -Recurse -File -ErrorAction SilentlyContinue
+    $files = [System.Collections.Generic.List[System.IO.FileInfo]]::new()
+
+    # Get files on module root
+    $ModuleOutputFolder | Get-ChildItem -File -ErrorAction SilentlyContinue | Where-Object -Property Name -NotLike '*.ps1' |
+        ForEach-Object { $files.Add($_) }
+
+    # Get files on module subfolders, excluding the following folders 'init', 'classes', 'public', 'private'
+    $skipList = @('init', 'classes', 'public', 'private')
+    $ModuleOutputFolder | Get-ChildItem -Directory | Where-Object { $_.Name -NotIn $skipList } |
+        Get-ChildItem -Recurse -File -ErrorAction SilentlyContinue | ForEach-Object { $files.Add($_) }
+
+    # Get the relative file path and store it in the manifest
     $files = $files | Select-Object -ExpandProperty FullName | ForEach-Object { $_.Replace($ModuleOutputFolder, '').TrimStart($pathSeparator) }
-    $fileList = $files | Where-Object { $_ -NotLike 'init*' -and $_ -NotLike 'classes*' -and $_ -NotLike 'public*' -and $_ -NotLike 'private*' }
     $manifest.FileList = $fileList.count -eq 0 ? @() : @($fileList)
     $manifest.FileList | ForEach-Object { Write-Verbose "[FileList] - [$_]" }
 
@@ -142,9 +154,9 @@ function Build-PSModuleManifest {
 
 
     Write-Verbose '[Gather]'
-    $capturedModules = @()
-    $capturedVersions = @()
-    $capturedPSEdition = @()
+    $capturedModules = [System.Collections.Generic.List[System.Object]]::new()
+    $capturedVersions = [System.Collections.Generic.List[string]]::new()
+    $capturedPSEdition = [System.Collections.Generic.List[string]]::new()
 
     $files = $ModuleOutputFolder | Get-ChildItem -Recurse -File -ErrorAction SilentlyContinue
     Write-Verbose "[Gather] - Processing [$($files.Count)] files"
@@ -165,22 +177,22 @@ function Build-PSModuleManifest {
                         $hashtable = '@\{[^}]*\}'
                         if ($_ -match $hashtable) {
                             Write-Verbose " - [#Requires -Modules] - [$_] - Hashtable"
-                            $capturedModules += ConvertTo-Hashtable -InputString $_
+                            $capturedModules.Add((ConvertTo-Hashtable -InputString $_))
                         } else {
                             Write-Verbose " - [#Requires -Modules] - [$_] - String"
-                            $capturedModules += $_
+                            $capturedModules.Add($_)
                         }
                     }
                 }
                 # PowerShellVersion -> REQUIRES -Version <N>[.<n>], $null if not provided
                 '^\s*#Requires -Version (.+)$' {
                     Write-Verbose " - [#Requires -Version] - [$($matches[1])]"
-                    $capturedVersions += $matches[1]
+                    $capturedVersions.Add($matches[1])
                 }
                 #CompatiblePSEditions -> REQUIRES -PSEdition <PSEdition-Name>, $null if not provided
                 '^\s*#Requires -PSEdition (.+)$' {
                     Write-Verbose " - [#Requires -PSEdition] - [$($matches[1])]"
-                    $capturedPSEdition += $matches[1]
+                    $capturedPSEdition.Add($matches[1])
                 }
             }
         }
@@ -244,7 +256,7 @@ function Build-PSModuleManifest {
     } catch {
         $repoLabels = @()
     }
-    $manifestTags = [Collections.Generic.List[string]]::new()
+    $manifestTags = [System.Collections.Generic.List[string]]::new()
     $tags = $PSData.Keys -contains 'Tags' ? ($PSData.Tags).Count -gt 0 ? $PSData.Tags : $repoLabels : $repoLabels
     $tags | ForEach-Object { $manifestTags.Add($_) }
     # Add tags for compatability mode. https://docs.microsoft.com/en-us/powershell/scripting/developer/module/how-to-write-a-powershell-module-manifest?view=powershell-7.1#compatibility-tags
@@ -322,7 +334,7 @@ function Build-PSModuleManifest {
     }
 
     Write-Verbose 'Creating new manifest file in outputs folder'
-    $outputManifestPath = Join-Path -Path $ModuleOutputFolder $manifestFileName
+    $outputManifestPath = Join-Path -Path $ModuleOutputFolder -ChildPath "$moduleName.psd1"
     Write-Verbose "OutputManifestPath - [$outputManifestPath]"
     New-ModuleManifest -Path $outputManifestPath @manifest
     Stop-LogGroup

diff --git a/scripts/helpers/Build/Get-PSModuleRootModule.ps1 b/scripts/helpers/Build/Get-PSModuleRootModule.ps1
diff --git a/scripts/main.ps1 b/scripts/main.ps1
@@ -10,8 +10,12 @@ Stop-LogGroup
 
 Start-LogGroup 'Loading inputs'
 $moduleName = ($env:GITHUB_ACTION_INPUT_Name | IsNullOrEmpty) ? $env:GITHUB_REPOSITORY_NAME : $env:GITHUB_ACTION_INPUT_Name
-$moduleSourceFolderPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath $env:GITHUB_ACTION_INPUT_Path $moduleName
 Write-Verbose "Module name:         [$moduleName]"
+
+$moduleSourceFolderPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath $env:GITHUB_ACTION_INPUT_Path $moduleName
+if (-not (Test-Path -Path $moduleSourceFolderPath)) {
+    $moduleSourceFolderPath = Join-Path -Path $env:GITHUB_WORKSPACE -ChildPath $env:GITHUB_ACTION_INPUT_Path
+}
 Write-Verbose "Source module path:  [$moduleSourceFolderPath]"
 if (-not (Test-Path -Path $moduleSourceFolderPath)) {
     throw "Module path [$moduleSourceFolderPath] does not exist."
@@ -23,6 +27,7 @@ $docsOutputFolderPath = Join-Path $env:GITHUB_WORKSPACE $env:GITHUB_ACTION_INPUT
 Write-Verbose "Docs output path:    [$docsOutputFolderPath]"
 Stop-LogGroup
 $params = @{
+    ModuleName              = $moduleName
     ModuleSourceFolderPath  = $moduleSourceFolderPath
     ModulesOutputFolderPath = $modulesOutputFolderPath
     DocsOutputFolderPath    = $docsOutputFolderPath

diff --git a/tests/src/PSModuleTest/PSModuleTest.psd1 b/tests/src/PSModuleTest/PSModuleTest.psd1