diff --git a/.github/workflows/Publish.yml b/.github/workflows/Publish.yml index c6ae27e..49305bc 100644 --- a/.github/workflows/Publish.yml +++ b/.github/workflows/Publish.yml @@ -3,7 +3,7 @@ name: Publish Module on: push: tags: - - '*' + - "*" workflow_dispatch: @@ -18,8 +18,10 @@ jobs: - name: 📥 Checkout uses: actions/checkout@v4 - - name: 📦 Install ModuleTools module form PSGallery - run: Install-PSResource -Repository PSGallery -Name ModuleTools -TrustRepository + - name: 📦 Install required modules from PSGallery + run: | + Install-PSResource -Repository PSGallery -Name ModuleTools -TrustRepository + Install-PSResource -Repository PSGallery -Name Microsoft.PowerShell.PlatyPS -TrustRepository - name: 🏗️ Build Module run: Invoke-MTBuild -Verbose @@ -45,4 +47,4 @@ jobs: exit 1 # Fail the workflow on error } env: - ApiKey: ${{ secrets.PSGALLERY_API }} \ No newline at end of file + ApiKey: ${{ secrets.PSGALLERY_API }} diff --git a/.github/workflows/Tests.yml b/.github/workflows/Tests.yml index d34b5ad..8817414 100644 --- a/.github/workflows/Tests.yml +++ b/.github/workflows/Tests.yml @@ -20,8 +20,10 @@ jobs: - name: 📥 Checkout uses: actions/checkout@v4 - - name: 📦 Install ModuleTools module form PSGallery - run: Install-PSResource -Repository PSGallery -Name ModuleTools -TrustRepository + - name: 📦 Install required modules from PSGallery + run: | + Install-PSResource -Repository PSGallery -Name ModuleTools -TrustRepository + Install-PSResource -Repository PSGallery -Name Microsoft.PowerShell.PlatyPS -TrustRepository - name: 🏗️ Build Module run: Invoke-MTBuild -Verbose @@ -36,4 +38,4 @@ jobs: $Report = New-MDHeader -Text "Output Files 📁" -Level 2 $Report += Get-ChildItem -Path ./dist -Recurse | Select-Object Name, Directory | New-MDTable echo "$Report" >> $env:GITHUB_STEP_SUMMARY - echo "$Report" \ No newline at end of file + echo "$Report" diff --git a/CHANGELOG.md b/CHANGELOG.md index 613a940..a47e6c4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ All notable changes to this project will be documented in this file. +## [1.8.0] - 2025-05-01 + +- Added support for assembly files (dll) + ## [1.3.0] - 2025-09-23 - Added support for `ps1xml1` format data. Place it in resources folder with `Name.format.ps1xml` to be automatically added as format file and imported in module manifest diff --git a/README.md b/README.md index d56f40b..3228775 100644 --- a/README.md +++ b/README.md @@ -45,6 +45,8 @@ All the Module files should be in inside `src` folder │ └──  New-PublicFunction.ps1 ├──  resources │ └──  some-config.json +├──  lib +│ └── Some-assembly.dll └──  classes └──  Person.classes.ps1 └──  Person.enums.ps1 @@ -61,6 +63,16 @@ Generated module is stored in dist folder, you can easily import it or publish i └──  TestModule.psm1 ``` +### Docs Folder + +Store `Microsoft.PowerShell.PlatyPs` generated markdown files in `docs` folder. If `docs` folder exists and contain valid markdown files, Build will generate MAML help file in the built module. + +``` + docs +├──  ModuleTools.md +└──  Invoke-MTBuild.md +``` + ### Project JSON File The `project.json` file contains all the important details about your module and is used during the module build. It should comply with a specific schema. You can refer to the sample `project-sample.json` file in the `example` directory for guidance. @@ -74,6 +86,10 @@ Run `New-MTModule` to generate the scaffolding; this will also create the `proje - All functions in the `private` folder are accessible internally within the module but are not exposed outside the module. - All `ps1` files in `classes` folder contains classes and enums, that are processed and placed in topmost of generated `psm1` files - Contents of the `src/resources` folder will be handled based on setting `copyResourcesToModuleRoot` +- +#### Lib Folder + +The `lib` folder within the `src` directory is intended for libraries and assempblies (dll files). When there is a library folder with dll files, it will be copied to module output dir and all dll are appended in module manifest as Required Assemblies. #### Resources Folder @@ -81,6 +97,8 @@ The `resources` folder within the `src` directory is intended for including any - **Configuration files**: Store any JSON, XML, or other configuration files needed by your module. - **Script files**: Place any scripts that are used by your functions or modules, but are not directly part of the public or private functions. +- **formatdata files**: Store `Example.Format.ps1xml` file for custom format data types to be imported to manifest +- **types files**: Store `Example.Types.ps1xml` file for custom types data types to be imported to manifest - **Documentation files**: Include any supplementary documentation that supports the usage or development of the module. - **Data files**: Store any data files that are used by your module, such as CSV or JSON files. - **Subfolder**: Include any additional folders and their content to be included with the module, such as dependant Modules, APIs, DLLs, etc... organized by a subfolder. diff --git a/docs/ModuleTools/Get-MTProjectInfo.md b/docs/ModuleTools/Get-MTProjectInfo.md new file mode 100644 index 0000000..4de9e02 --- /dev/null +++ b/docs/ModuleTools/Get-MTProjectInfo.md @@ -0,0 +1,77 @@ +--- +document type: cmdlet +external help file: ModuleTools-Help.xml +HelpUri: '' +Locale: en-US +Module Name: ModuleTools +ms.date: 03/19/2026 +PlatyPS schema version: 2024-05-01 +title: Get-MTProjectInfo +--- + +# Get-MTProjectInfo + +## SYNOPSIS + +Retrieves information about a project by reading data from a project.json file in ModuleTools project folder. + +## SYNTAX + +### __AllParameterSets + +``` +Get-MTProjectInfo [[-Path] ] [] +``` + +## ALIASES + +## DESCRIPTION + +The Get-MTProjectInfo function retrieves information about a project by reading data from a project.json file located in the current directory. +Ensure you navigate to a module directory which has project.json in root directory. +Most variables are already defined in output of this command which can be used in pester tests and other configs. + +## EXAMPLES + +### EXAMPLE 1 + +Get-MTProjectInfo +Retrieves project information from the project.json file in the current directory. Useful for debuggin and writing pester tests. + +## PARAMETERS + +### -Path + +Provide path to root folder of the ModuleTool based project + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +## INPUTS + +## OUTPUTS + +### hastable with all project data. + +{{ Fill in the Description }} + +## NOTES + +## RELATED LINKS + +{{ Fill in the related links here }} + diff --git a/docs/ModuleTools/Invoke-MTBuild.md b/docs/ModuleTools/Invoke-MTBuild.md new file mode 100644 index 0000000..b2903bf --- /dev/null +++ b/docs/ModuleTools/Invoke-MTBuild.md @@ -0,0 +1,63 @@ +--- +document type: cmdlet +external help file: ModuleTools-Help.xml +HelpUri: '' +Locale: en-US +Module Name: ModuleTools +ms.date: 03/19/2026 +PlatyPS schema version: 2024-05-01 +title: Invoke-MTBuild +--- + +# Invoke-MTBuild + +## SYNOPSIS + +Build a ModuleTool project to generate ready to import PowerShell Module. + +## SYNTAX + +### __AllParameterSets + +``` +Invoke-MTBuild [] +``` + +## ALIASES + +This cmdlet has the following aliases, + {{Insert list of aliases}} + +## DESCRIPTION + +This function is used to build a module, dist folder is cleaned up and whole module is build from scracth. +copies all necessary resource files. + +## EXAMPLES + +### EXAMPLE 1: Builds module from the project files. + +Invoke-MTBuild + +### EXAMPLE 2: Builds module and outputs verbose details during entire workflow. + +Invoke-MTBuild -Verbose + +## PARAMETERS + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +{{ Fill in the related links here }} \ No newline at end of file diff --git a/docs/ModuleTools/Invoke-MTTest.md b/docs/ModuleTools/Invoke-MTTest.md new file mode 100644 index 0000000..a2feab1 --- /dev/null +++ b/docs/ModuleTools/Invoke-MTTest.md @@ -0,0 +1,112 @@ +--- +document type: cmdlet +external help file: ModuleTools-Help.xml +HelpUri: '' +Locale: en-US +Module Name: ModuleTools +ms.date: 03/19/2026 +PlatyPS schema version: 2024-05-01 +title: Invoke-MTTest +--- + +# Invoke-MTTest + +## SYNOPSIS + +Runs Pester tests using settings from project.json + +## SYNTAX + +### __AllParameterSets + +``` +Invoke-MTTest [[-TagFilter] ] [[-ExcludeTagFilter] ] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + {{Insert list of aliases}} + +## DESCRIPTION + +Run Pester tests using the specified configuration and settings as defined in project.json. Place all your tests in "tests" folder + +## EXAMPLES + +### EXAMPLE 1 + +Invoke-MTTest +Runs the Pester tests for the project. + +### EXAMPLE 2 + +Invoke-MTTest -TagFilter "unit","integrate" +Runs the Pester tests for the project, that has tag unit or integrate + +### EXAMPLE 3 + +Invoke-MTTest -ExcludeTagFilter "unit" +Runs the Pester tests for the project, excludes any test with tag unit + +## PARAMETERS + +### -ExcludeTagFilter + +Array of tags to exclude, Provide the tag Pester should exclude + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 1 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -TagFilter + +Array of tags to run, Provide the tag Pester should run + +```yaml +Type: System.String[] +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +{{ Fill in the related links here }} + diff --git a/docs/ModuleTools/ModuleTools.md b/docs/ModuleTools/ModuleTools.md new file mode 100644 index 0000000..0b08230 --- /dev/null +++ b/docs/ModuleTools/ModuleTools.md @@ -0,0 +1,44 @@ +--- +document type: module +Help Version: 1.0.0.0 +HelpInfoUri: '' +Locale: en-US +Module Guid: d1595b4a-a79f-4440-94f0-3196f4d29c41 +Module Name: ModuleTools +ms.date: 03/19/2026 +PlatyPS schema version: 2024-05-01 +title: ModuleTools Module +--- + +# ModuleTools Module + +## Description + +ModuleTools is a versatile, standalone PowerShell module builder. Create anything from simple to robust modules with ease. Built for CICD and Automation. + +## ModuleTools Cmdlets + +### [Get-MTProjectInfo](Get-MTProjectInfo.md) + +Retrieves information about a project by reading data from a project.json file in ModuleTools project folder. + +### [Invoke-MTBuild](Invoke-MTBuild.md) + +Build a ModuleTool project to generate ready to import PowerShell Module. + +### [Invoke-MTTest](Invoke-MTTest.md) + +Runs Pester tests using settings from project.json + +### [New-MTModule](New-MTModule.md) + +Create module scaffolding along with project.json file to easily build and manage modules in ModuleTools opinionated format + +### [Publish-MTLocal](Publish-MTLocal.md) + +Copy built module to local PSModulePath. + +### [Update-MTModuleVersion](Update-MTModuleVersion.md) + +Updates the version number of a module in project.json file. Uses [semver] object type. + diff --git a/docs/ModuleTools/New-MTModule.md b/docs/ModuleTools/New-MTModule.md new file mode 100644 index 0000000..5186d3f --- /dev/null +++ b/docs/ModuleTools/New-MTModule.md @@ -0,0 +1,129 @@ +--- +document type: cmdlet +external help file: ModuleTools-Help.xml +HelpUri: '' +Locale: en-US +Module Name: ModuleTools +ms.date: 03/19/2026 +PlatyPS schema version: 2024-05-01 +title: New-MTModule +--- + +# New-MTModule + +## SYNOPSIS + +Create module scaffolding along with project.json file to easily build and manage modules in ModuleTools opinionated format + +## SYNTAX + +### __AllParameterSets + +``` +New-MTModule [[-Path] ] [-WhatIf] [-Confirm] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + {{Insert list of aliases}} + +## DESCRIPTION + +This command creates folder structure and project.json file easily. Use this to quikcly setup a ModuleTools compatible module. Provide all the paramters to command or enter details in the interactive prompts with sane defaults. + +## EXAMPLES + +### EXAMPLE 1 + +New-MTModule -Path c:\work +Creates module inside c:\work folder + +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Path + +Path where module will be created. + +```yaml +Type: System.String +DefaultValue: (Get-Location).Path +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Runs the command in a mode that only reports what would happen without performing the actions. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +The structure of the ModuleTools module is meticulously designed according to PowerShell best practices for module development. +While some design decisions may seem unconventional, they are made to ensure that ModuleTools and the process of building modules remain straightforward and easy to manage. + + +## RELATED LINKS + +{{ Fill in the related links here }} + diff --git a/docs/ModuleTools/Publish-MTLocal.md b/docs/ModuleTools/Publish-MTLocal.md new file mode 100644 index 0000000..98dc8fe --- /dev/null +++ b/docs/ModuleTools/Publish-MTLocal.md @@ -0,0 +1,92 @@ +--- +document type: cmdlet +external help file: ModuleTools-Help.xml +HelpUri: '' +Locale: en-US +Module Name: ModuleTools +ms.date: 03/19/2026 +PlatyPS schema version: 2024-05-01 +title: Publish-MTLocal +--- + +# Publish-MTLocal + +## SYNOPSIS + +Copy built module to local PSModulePath. + +## SYNTAX + +### __AllParameterSets + +``` +Publish-MTLocal [[-ModuleDirectoryPath] ] [] +``` + +## ALIASES + +This cmdlet has the following aliases, + {{Insert list of aliases}} + +## DESCRIPTION + +Useful quick testing and private modules which don't get hosted in PSGallery or other repository. This command publishes the generated module to local PSModulePath location which gets autoimported when porfile loads. + +## EXAMPLES + +### Example 1 + +Publish-MTLocal +Publishes to local $PSModulePath + +### Example 2 + +Publish-MTLocal -ModuleDirectoryPath \\Some\Path +Publishes/Copies to path provided + +## PARAMETERS + +### -ModuleDirectoryPath + +Path to save the built module. + +```yaml +Type: System.String +DefaultValue: '' +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +### System.Object + +{{ Fill in the Description }} + +## NOTES + +{{ Fill in the Notes }} + +## RELATED LINKS + +{{ Fill in the related links here }} + diff --git a/docs/ModuleTools/Update-MTModuleVersion.md b/docs/ModuleTools/Update-MTModuleVersion.md new file mode 100644 index 0000000..8d66518 --- /dev/null +++ b/docs/ModuleTools/Update-MTModuleVersion.md @@ -0,0 +1,185 @@ +--- +document type: cmdlet +external help file: ModuleTools-Help.xml +HelpUri: '' +Locale: en-US +Module Name: ModuleTools +ms.date: 03/19/2026 +PlatyPS schema version: 2024-05-01 +title: Update-MTModuleVersion +--- + +# Update-MTModuleVersion + +## SYNOPSIS + +Updates the version number of a module in project.json file. Uses [semver] object type. + +## SYNTAX + +### __AllParameterSets + +``` +Update-MTModuleVersion [[-Label] ] [-PreviewRelease] [-StableRelease] [-WhatIf] [-Confirm] + [] +``` + +## ALIASES + +This cmdlet has the following aliases, + {{Insert list of aliases}} + +## DESCRIPTION + +This script updates the version number of a PowerShell module by modifying the project.json file, which gets written into module manifest file (.psd1). +[semver] is supported only powershell 7 and above. +It increments the version number based on the specified version part (Major, Minor, Patch). +Can also attach preview/stable release to Release property + +## EXAMPLES + +### EXAMPLE 1 + +Update-MTModuleVersion -Label Major +Updates the Major version part of the module. Version 2.1.3 will become 3.0.0. + +### EXAMPLE 2 + +Update-MTModuleVersion +Updates the Patch version part of the module. Version 2.1.3 will become 2.1.4 + +### EXAMPLE 3 + +Update-MTModuleVersion -PreviewRelease +Updates the Patch version part of the module. Version 2.1.6 will become 2.1.7-preview + +## PARAMETERS + +### -Confirm + +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: +- cf +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -Label + +The part of the version number to increment (Major, Minor, Patch). +Default is patch. + +```yaml +Type: System.String +DefaultValue: Patch +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: 0 + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -PreviewRelease + +Use this to use semantic version and attach release name as 'preview' which is supported by PowerShell gallery, to remove it use stable release parameter + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -StableRelease + +Use this to use semantic version and removes 'preview' release name converting it to stable release + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: False +SupportsWildcards: false +Aliases: [] +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### -WhatIf + +Runs the command in a mode that only reports what would happen without performing the actions. + +```yaml +Type: System.Management.Automation.SwitchParameter +DefaultValue: '' +SupportsWildcards: false +Aliases: +- wi +ParameterSets: +- Name: (All) + Position: Named + IsRequired: false + ValueFromPipeline: false + ValueFromPipelineByPropertyName: false + ValueFromRemainingArguments: false +DontShow: false +AcceptedValues: [] +HelpMessage: '' +``` + +### CommonParameters + +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, +-InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, +-ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see +[about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +Ensure you are in project directory when you run this command. + + +## RELATED LINKS + +{{ Fill in the related links here }} + diff --git a/project.json b/project.json index c400f70..a60df32 100644 --- a/project.json +++ b/project.json @@ -1,11 +1,11 @@ { "ProjectName": "ModuleTools", "Description": "ModuleTools is a versatile, standalone PowerShell module builder. Create anything from simple to robust modules with ease. Built for CICD and Automation.", - "Version": "1.3.0", + "Version": "1.8.1", "copyResourcesToModuleRoot": false, "Manifest": { "Author": "Manjunath Beli", - "PowerShellHostVersion": "7.4", + "PowerShellHostVersion": "7.3", "GUID": "d1595b4a-a79f-4440-94f0-3196f4d29c41", "Tags": [], "ProjectUri": "https://github.com/belibug/ModuleTools" diff --git a/src/private/BuildHelp.ps1 b/src/private/BuildHelp.ps1 new file mode 100644 index 0000000..e3a527b --- /dev/null +++ b/src/private/BuildHelp.ps1 @@ -0,0 +1,33 @@ +function Build-Help { + [CmdletBinding()] + param( + ) + Write-Verbose 'Running Help update' + + $data = Get-MTProjectInfo + $helpMarkdownFiles = Get-ChildItem -Path $data.DocsDir -Filter '*.md' -Recurse + + if (-not $helpMarkdownFiles) { + Write-Verbose 'No help markdown files in docs directory, skipping building help' + return + } + + if (-not (Get-Module -Name Microsoft.PowerShell.PlatyPS -ListAvailable)) { + throw 'The module Microsoft.PowerShell.PlatyPS must be installed for Markdown documentation to be generated.' + } + + $AllCommandHelpFiles = $helpMarkdownFiles | Measure-PlatyPSMarkdown | Where-Object FileType -Match CommandHelp + + # Export to Dist folder + $AllCommandHelpFiles | Import-MarkdownCommandHelp -Path { $_.FilePath } | + Export-MamlCommandHelp -OutputFolder $data.OutputModuleDir | Out-Null + + # Rename the directory to match locale + $HelpDirOld = Join-Path $data.OutputModuleDir $Data.ProjectName + #TODO: hardcoded locale to en-US, change it based on Doc type + $languageLocale = 'en-US' + $HelpDirNew = Join-Path $data.OutputModuleDir $languageLocale + Write-Verbose "Renamed folder to locale: $languageLocale" + + Rename-Item -Path $HelpDirOld -NewName $HelpDirNew +} \ No newline at end of file diff --git a/src/private/Build.Manifest.ps1 b/src/private/BuildManifest.ps1 similarity index 54% rename from src/private/Build.Manifest.ps1 rename to src/private/BuildManifest.ps1 index c127374..72fd0d2 100644 --- a/src/private/Build.Manifest.ps1 +++ b/src/private/BuildManifest.ps1 @@ -12,9 +12,9 @@ function Build-Manifest { $aliasToExport += Get-AliasInFunctionFromFile -filePath $_ } - ## Import Formatting (if any) + ## Import Format.ps1xml (if any) $FormatsToProcess = @() - Get-ChildItem -Path $data.ResourcesDir -File -Filter '*.ps1xml' -ErrorAction SilentlyContinue | ForEach-Object { + Get-ChildItem -Path $data.ResourcesDir -File -Filter '*Format.ps1xml' -ErrorAction SilentlyContinue | ForEach-Object { if ($data.copyResourcesToModuleRoot) { $FormatsToProcess += $_.Name } else { @@ -22,16 +22,34 @@ function Build-Manifest { } } + ## Import Types.ps1xml1 (if any) + $TypesToProcess = @() + Get-ChildItem -Path $data.ResourcesDir -File -Filter '*Types.ps1xml' -ErrorAction SilentlyContinue | ForEach-Object { + if ($data.copyResourcesToModuleRoot) { + $TypesToProcess += $_.Name + } else { + $TypesToProcess += Join-Path -Path 'resources' -ChildPath $_.Name + } + } + + ## load assemblies from lib (if any) + $RequiredAssemblies = @() + Get-ChildItem -Path $data.LibDir -File -Filter '*.dll' -ErrorAction SilentlyContinue | ForEach-Object { + $RequiredAssemblies += [System.IO.Path]::Join('.', 'lib', $_.Name) + } + $ManfiestAllowedParams = (Get-Command New-ModuleManifest).Parameters.Keys $sv = [semver]$data.Version $ParmsManifest = @{ - Path = $data.ManifestFilePSD1 - Description = $data.Description - FunctionsToExport = $functionToExport - AliasesToExport = $aliasToExport - RootModule = "$($data.ProjectName).psm1" - ModuleVersion = [version]$sv - FormatsToProcess = $FormatsToProcess + Path = $data.ManifestFilePSD1 + Description = $data.Description + FunctionsToExport = $functionToExport + AliasesToExport = $aliasToExport + RootModule = "$($data.ProjectName).psm1" + ModuleVersion = [version]$sv + FormatsToProcess = $FormatsToProcess + TypesToProcess = $TypesToProcess + RequiredAssemblies = $RequiredAssemblies } ## Release lable diff --git a/src/private/Build-Module.ps1 b/src/private/BuildModule.ps1 similarity index 100% rename from src/private/Build-Module.ps1 rename to src/private/BuildModule.ps1 diff --git a/src/private/CopyLib.ps1 b/src/private/CopyLib.ps1 new file mode 100644 index 0000000..b68e32b --- /dev/null +++ b/src/private/CopyLib.ps1 @@ -0,0 +1,8 @@ +function Copy-LibFolder { + $data = Get-MTProjectInfo + $libFolder = $data.LibDir + if (Test-Path $libFolder -ErrorAction SilentlyContinue) { + Write-Verbose 'Found lib folder, copying content to module' + Copy-Item -Path $libFolder -Destination ($data.OutputModuleDir) -Recurse -Force -ErrorAction Stop + } +} \ No newline at end of file diff --git a/src/private/GetLocalModulePath.ps1 b/src/private/GetLocalModulePath.ps1 new file mode 100644 index 0000000..6712f8c --- /dev/null +++ b/src/private/GetLocalModulePath.ps1 @@ -0,0 +1,24 @@ +function Get-LocalModulePath { + $sep = [IO.Path]::PathSeparator + + $ModulePaths = $env:PSModulePath -split $sep | ForEach-Object { $_.Trim() } | Select-Object -Unique + + if ($IsWindows) { + $MatchPattern = '\\Documents\\PowerShell\\Modules' + $Result = $ModulePaths | Where-Object { $_ -match $MatchPattern } | Select-Object -First 1 + if ($Result -and (Test-Path $Result)) { + return $Result + } else { + throw "No windows module path matching $MatchPattern found" + } + } else { + # For Mac and Linux + $MatchPattern = '/\.local/share/powershell/Modules$' + $Result = $ModulePaths | Where-Object { $_ -match $MatchPattern } | Select-Object -First 1 + if ($Result -and (Test-Path $Result)) { + return $Result + } else { + throw "No macOS/Linux module path matching $MatchPattern found in PSModulePath." + } + } +} \ No newline at end of file diff --git a/src/public/GetMTProjectInfo.ps1 b/src/public/GetMTProjectInfo.ps1 index 23c9f88..6862641 100644 --- a/src/public/GetMTProjectInfo.ps1 +++ b/src/public/GetMTProjectInfo.ps1 @@ -1,47 +1,40 @@ -<# -.SYNOPSIS -Retrieves information about a project by reading data from a project.json file in ModuleTools project folder. - -.DESCRIPTION -The Get-MTProjectInfo function retrieves information about a project by reading data from a project.json file located in the current directory. Ensure you navigate to a module directory which has project.json in root directory. Most variables are already defined in output of this command which can be used in pester tests and other configs. - -.PARAMETER None -This function does not accept any parameters. - -.EXAMPLE -Get-MTProjectInfo -Retrieves project information from the project.json file in the current directory. Useful for debuggin and writing pester tests. - -.OUTPUTS -hastable with all project data. - -#> function Get-MTProjectInfo { - $Out = @{} - $ProjectRoot = Get-Location | Convert-Path - $Out['ProjecJSON'] = Join-Path -Path $ProjectRoot -ChildPath 'project.json' + [CmdletBinding()] + param( + [Parameter(Position = 0)] + [string]$Path = (Get-Location).Path + ) + $ProjectRoot = (Resolve-Path -LiteralPath $Path).Path + $ProjectJson = [System.IO.Path]::Join($ProjectRoot, 'project.json') - if (-not (Test-Path $Out.ProjecJSON)) { - Write-Error 'Not a Project folder, project.json not found' -ErrorAction Stop + if (-not (Test-Path -LiteralPath $projectJson)) { + throw "Not a project folder. project.json not found: $projectJson" } + + $jsonData = Get-Content -LiteralPath $projectJson -Raw | ConvertFrom-Json -AsHashtable + + $Out = @{} + $Out['ProjectJSON'] = $ProjectJson - ## Metadata, Import all json data - $jsonData = Get-Content -Path $Out.ProjecJSON | ConvertFrom-Json -AsHashtable foreach ($key in $jsonData.Keys) { $Out[$key] = $jsonData[$key] } - $ProjectName = $Out.ProjectName + $Out.ProjectJson = $projectJson + $Out.PSTypeName = 'MTProjectInfo' + $ProjectName = $jsonData.ProjectName + ## Folders $Out['ProjectRoot'] = $ProjectRoot $Out['PublicDir'] = [System.IO.Path]::Join($ProjectRoot, 'src', 'public') $Out['PrivateDir'] = [System.IO.Path]::Join($ProjectRoot, 'src', 'private') $Out['ClassesDir'] = [System.IO.Path]::Join($ProjectRoot, 'src', 'classes') $Out['ResourcesDir'] = [System.IO.Path]::Join($ProjectRoot, 'src', 'resources') + $Out['LibDir'] = [System.IO.Path]::Join($ProjectRoot, 'src', 'lib') + $Out['DocsDir'] = [System.IO.Path]::Join($ProjectRoot, 'docs') $Out['OutputDir'] = [System.IO.Path]::Join($ProjectRoot, 'dist') $Out['OutputModuleDir'] = [System.IO.Path]::Join($Out.OutputDir, $ProjectName) $Out['ModuleFilePSM1'] = [System.IO.Path]::Join($Out.OutputModuleDir, "$ProjectName.psm1") $Out['ManifestFilePSD1'] = [System.IO.Path]::Join($Out.OutputModuleDir, "$ProjectName.psd1") - $Output = [pscustomobject]$Out | Add-Member -TypeName MTProjectInfo -PassThru - return $Output + return [pscustomobject]$out } \ No newline at end of file diff --git a/src/public/InvokeMTBuild.ps1 b/src/public/InvokeMTBuild.ps1 index b9c6fee..62cbc4d 100644 --- a/src/public/InvokeMTBuild.ps1 +++ b/src/public/InvokeMTBuild.ps1 @@ -1,17 +1,3 @@ -<# -.SYNOPSIS - Invokes the process to build a module in ModuleTools format. - -.DESCRIPTION - This function is used to build a module, dist folder is cleaned up and whole module is build from scracth. copies all necessary resource files. - -.PARAMETER None - This function does not accept any parameters. - -.EXAMPLE - Invoke-MTBuild - Invokes the process to build a module. -#> function Invoke-MTBuild { [CmdletBinding()] param ( @@ -20,5 +6,7 @@ function Invoke-MTBuild { Reset-ProjectDist Build-Module Build-Manifest + Build-Help Copy-ProjectResource + Copy-LibFolder } \ No newline at end of file diff --git a/src/public/InvokeMTTests.ps1 b/src/public/InvokeMTTests.ps1 index 2d79351..65954d7 100644 --- a/src/public/InvokeMTTests.ps1 +++ b/src/public/InvokeMTTests.ps1 @@ -1,28 +1,3 @@ -<# -.SYNOPSIS -Runs Pester tests for using settings from project.json - -.DESCRIPTION -This function runs Pester tests using the specified configuration and settings in project.json. Place all your tests in "tests" folder - -.PARAMETER TagFilter -Array of tags to run, Provide the tag Pester should run - -.PARAMETER ExcludeTagFilter -Array of tags to exclude, Provide the tag Pester should exclude - -.EXAMPLE -Invoke-MTTest -Runs the Pester tests for the project. - -.EXAMPLE -Invoke-MTTest -TagFilter "unit","integrate" -Runs the Pester tests for the project, that has tag unit or integrate - -.EXAMPLE -Invoke-MTTest -ExcludeTagFilter "unit" -Runs the Pester tests for the project, excludes any test with tag unit -#> function Invoke-MTTest { [CmdletBinding()] param ( diff --git a/src/public/NewMTModule.ps1 b/src/public/NewMTModule.ps1 index 02a42b6..46df329 100644 --- a/src/public/NewMTModule.ps1 +++ b/src/public/NewMTModule.ps1 @@ -1,20 +1,3 @@ -<# -.SYNOPSIS -Create module scaffolding along with project.json file to easily build and manage modules - -.DESCRIPTION -This command creates folder structure and project.json file easily. Use this to quikcly setup a ModuleTools compatible module. - -.PARAMETER Path -Path where module will be created. Provide root folder path, module folder will be created as subdirectory. Path should be valid. - -.EXAMPLE -New-MTModule -Path c:\work -# Creates module inside c:\work folder - -.NOTES -The structure of the ModuleTools module is meticulously designed according to PowerShell best practices for module development. While some design decisions may seem unconventional, they are made to ensure that ModuleTools and the process of building modules remain straightforward and easy to manage. -#> function New-MTModule { [CmdletBinding(SupportsShouldProcess = $true)] param ( diff --git a/src/public/PublishMTLocal.ps1 b/src/public/PublishMTLocal.ps1 new file mode 100644 index 0000000..ef786ad --- /dev/null +++ b/src/public/PublishMTLocal.ps1 @@ -0,0 +1,35 @@ +function Publish-MTLocal { + [CmdletBinding()] + param( + [string]$ModuleDirectoryPath + ) + + if ($ModuleDirectoryPath) { + if (-not (Test-Path $ModuleDirectoryPath -PathType Container)) { + New-Item $ModuleDirectoryPath -ItemType Directory -Force | Out-Null + } + } else { + $ModuleDirectoryPath = Get-LocalModulePath + } + + Write-Verbose "Using $ModuleDirectoryPath as path" + + $ProjectInfo = Get-MTProjectInfo + + # Ensure module is locally built and ready + if (-not (Test-Path $ProjectInfo.OutputModuleDir)) { + throw 'Dist folder is empty, build the module before running publish command' + } + + # Cleanup old files + $OldModule = Join-Path -Path $ModuleDirectoryPath -ChildPath $ProjectInfo.ProjectName + if (Test-Path -Path $OldModule) { + Write-Verbose 'Removing old module files' + Remove-Item -Recurse $OldModule -Force + } + + # Copy New Files + Write-Verbose 'Copying new Files' + Copy-Item -Path $ProjectInfo.OutputModuleDir -Destination $ModuleDirectoryPath -Recurse -ErrorAction Stop + Write-Verbose 'Module copy to local path complete, Refresh session or import module manually' +} \ No newline at end of file diff --git a/src/public/UpdateModVersion.ps1 b/src/public/UpdateModVersion.ps1 index 01eca5a..d0a0817 100644 --- a/src/public/UpdateModVersion.ps1 +++ b/src/public/UpdateModVersion.ps1 @@ -1,28 +1,3 @@ -<# -.SYNOPSIS -Updates the version number of a module in project.json file. Uses [semver] object type. - -.DESCRIPTION -This script updates the version number of a PowerShell module by modifying the project.json file, which gets written into module manifest file (.psd1). [semver] is supported only powershell 7 and above. -It increments the version number based on the specified version part (Major, Minor, Patch). Can also attach preview/stable release to Release property of - -.PARAMETER Label -The part of the version number to increment (Major, Minor, Patch). Default is patch. - -.PARAMETER PreviewRelease -Use this to use semantic version and attach release name as 'preview' which is supported by PowerShell gallery, to remove it use stable release parameter - -.EXAMPLE -Update-MTModuleVersion -Label Major -Updates the Major version part of the module. Version 2.1.3 will become 3.1.3 - -.EXAMPLE -Update-MTModuleVersion -Updates the Patch version part of the module. Version 2.1.3 will become 2.1.4 - -.NOTES -Ensure you are in project directory when you run this command. -#> function Update-MTModuleVersion { [CmdletBinding(SupportsShouldProcess = $true)] param( @@ -34,7 +9,7 @@ function Update-MTModuleVersion { Write-Verbose 'Running Version Update' $data = Get-MTProjectInfo - $jsonContent = Get-Content -Path $data.ProjecJSON | ConvertFrom-Json + $jsonContent = Get-Content -Path $data.ProjectJSON | ConvertFrom-Json [semver]$CurrentVersion = $jsonContent.Version $Major = $CurrentVersion.Major @@ -69,5 +44,5 @@ function Update-MTModuleVersion { $newJsonContent = $jsonContent | ConvertTo-Json # Write the updated JSON back to the file - $newJsonContent | Set-Content -Path $data.ProjecJSON + $newJsonContent | Set-Content -Path $data.ProjectJSON } \ No newline at end of file