diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dd2e5f0..9139ba9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,13 +10,15 @@ on: - 'PSDepend/**' - 'Tests/**' - 'build.ps1' - - 'psake.ps1' + - 'psakeFile.ps1' + - 'requirements.psd1' pull_request: paths: - 'PSDepend/**' - 'Tests/**' - 'build.ps1' - - 'psake.ps1' + - 'psakeFile.ps1' + - 'requirements.psd1' workflow_dispatch: jobs: @@ -29,15 +31,15 @@ jobs: os: [ubuntu-latest, windows-latest, macOS-latest] steps: - uses: actions/checkout@v4 - - name: Test + - name: Bootstrap and Test shell: pwsh - run: ./build.ps1 -Task Test + run: ./build.ps1 -Bootstrap -Task Test - name: Upload Test Results if: always() uses: actions/upload-artifact@v4 with: name: testResults-${{ matrix.os }} - path: ./Tests/out/testResults.xml + path: ./Output/testResults.xml publish-test-results: name: Publish Test Results diff --git a/appveyor.yml b/appveyor.yml deleted file mode 100644 index b92a324..0000000 --- a/appveyor.yml +++ /dev/null @@ -1,20 +0,0 @@ -# See http://www.appveyor.com/docs/appveyor-yml for many more options - -#Publish to PowerShell Gallery with this key -environment: - NuGetApiKey: - secure: oqMFzG8F65K5l572V7VzlZIWU7xnSYDLtSXECJAAURrXe8M2+BAp9vHLT+1h1lR0 - -# Allow WMF5 (i.e. PowerShellGallery functionality) -os: WMF 5 - -# Skip on updates to the readme. -# We can force this by adding [skip ci] or [ci skip] anywhere in commit message -skip_commits: - message: /updated readme.*|update readme.*s/ - -build: false - -#Kick off the CI/CD pipeline -test_script: - - ps: . .\build.ps1 \ No newline at end of file diff --git a/build.ps1 b/build.ps1 index 81c53e7..6e14267 100644 --- a/build.ps1 +++ b/build.ps1 @@ -1,18 +1,62 @@ -[CmdletBinding()] -param ( - [parameter(Position = 0)] - [ValidateSet('Default','Init','Test','Build','Deploy')] - $Task = 'Default' +[Diagnostics.CodeAnalysis.SuppressMessageAttribute( + 'PSReviewUnusedParameter', + 'Command', + Justification = 'false positive' +)] +[Diagnostics.CodeAnalysis.SuppressMessageAttribute( + 'PSReviewUnusedParameter', + 'Parameter', + Justification = 'false positive' +)] +[Diagnostics.CodeAnalysis.SuppressMessageAttribute( + 'PSReviewUnusedParameter', + 'CommandAst', + Justification = 'false positive' +)] +[Diagnostics.CodeAnalysis.SuppressMessageAttribute( + 'PSReviewUnusedParameter', + 'FakeBoundParams', + Justification = 'false positive' +)] +[CmdletBinding(DefaultParameterSetName = 'task')] +param( + [parameter(ParameterSetName = 'task', Position = 0)] + [ArgumentCompleter( { + param($Command, $Parameter, $WordToComplete, $CommandAst, $FakeBoundParams) + try { + Get-PSakeScriptTasks -BuildFile './psakeFile.ps1' -ErrorAction 'Stop' | + Where-Object { $_.Name -like "$WordToComplete*" } | + Select-Object -ExpandProperty 'Name' + } catch { + @() + } + })] + [string[]]$Task = 'default', + [switch]$Bootstrap, + [parameter(ParameterSetName = 'Help')] + [switch]$Help ) -# Grab nuget bits, install modules, set build variables, start build. -Get-PackageProvider -Name NuGet -ForceBootstrap | Out-Null +$ErrorActionPreference = 'Stop' +$psakeFile = './psakeFile.ps1' -Install-Module Psake, PSDeploy, BuildHelpers -force -AllowClobber -Scope CurrentUser -Install-Module Pester -RequiredVersion 4.10.1 -Force -AllowClobber -SkipPublisherCheck -Scope CurrentUser -Import-Module Psake, BuildHelpers +if ($Bootstrap) { + if (-not (Get-PackageProvider -Name NuGet -ErrorAction SilentlyContinue)) { + Install-PackageProvider -Name NuGet -Force -Scope CurrentUser | Out-Null + } + Set-PSRepository -Name PSGallery -InstallationPolicy Trusted + if (-not (Get-Module -Name PSDepend -ListAvailable)) { + Install-Module -Name PSDepend -Repository PSGallery -Scope CurrentUser -Force -RequiredVersion '0.3.8' + } + Import-Module -Name PSDepend -Verbose:$false + Invoke-PSDepend -Path './requirements.psd1' -Install -Import -Force -WarningAction SilentlyContinue +} -Set-BuildEnvironment -ErrorAction SilentlyContinue - -Invoke-psake -buildFile $ENV:BHProjectPath\psake.ps1 -taskList $Task -nologo -exit ( [int]( -not $psake.build_success ) ) +if ($PSCmdlet.ParameterSetName -eq 'Help') { + Get-PSakeScriptTasks -BuildFile $psakeFile | + Format-Table -Property Name, Description, Alias, DependsOn +} else { + Set-BuildEnvironment -Force + Invoke-Psake -BuildFile $psakeFile -TaskList $Task -NoLogo + exit ([int](-not $psake.build_success)) +} \ No newline at end of file diff --git a/deploy.psdeploy.ps1 b/deploy.psdeploy.ps1 deleted file mode 100644 index 65a21d9..0000000 --- a/deploy.psdeploy.ps1 +++ /dev/null @@ -1,29 +0,0 @@ -# Generic module deployment. -# This stuff should be moved to psake for a cleaner deployment view - -# ASSUMPTIONS: - - # folder structure of: - # - RepoFolder - # - This PSDeploy file - # - ModuleName - # - ModuleName.psd1 - - # Nuget key in $ENV:NugetApiKey - - # Set-BuildEnvironment from BuildHelpers module has populated ENV:BHProjectName - -# find a folder that has psd1 of same name... - -if($ENV:BHProjectName -and $ENV:BHProjectName.Count -eq 1) -{ - Deploy Module { - By PSGalleryModule { - FromSource $ENV:BHProjectName - To PSGallery - WithOptions @{ - ApiKey = $ENV:NugetApiKey - } - } - } -} \ No newline at end of file diff --git a/docs/en-US/Get-Dependency.md b/docs/en-US/Get-Dependency.md new file mode 100644 index 0000000..6a06fa6 --- /dev/null +++ b/docs/en-US/Get-Dependency.md @@ -0,0 +1,162 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Get-Dependency + +## SYNOPSIS + +Read a dependency psd1 file. + +## SYNTAX + +### File (Default) +``` +Get-Dependency [-Path ] [-Tags ] [-Recurse] [-Credentials ] + [-ProgressAction ] [] +``` + +### Hashtable +``` +Get-Dependency [-Tags ] [-InputObject ] [-Credentials ] + [-ProgressAction ] [] +``` + +## DESCRIPTION + +Reads a PSDepend dependency file (.psd1) and returns structured dependency objects. + +## EXAMPLES + +### Example 1 + +```powershell +Get-Dependency -Path .\requirements.psd1 +``` + +Returns all dependencies defined in requirements.psd1. + +### Example 2 + +```powershell +Get-Dependency -Path . -Recurse -Tags 'prod' +``` + +Recursively finds all dependency files under the current directory and returns dependencies tagged 'prod'. + +## PARAMETERS + +### -Path + +Path to project root or a specific dependency file. + +```yaml +Type: String[] +Parameter Sets: File +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Tags + +Limit results to dependencies with one or more matching tags. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Recurse + +Search recursively for dependency files under Path. + +```yaml +Type: SwitchParameter +Parameter Sets: File +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -InputObject + +Treat a hashtable as dependency file contents rather than reading from disk. + +```yaml +Type: Hashtable[] +Parameter Sets: Hashtable +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +Hashtable of PSCredentials keyed by credential name for private feeds. + +```yaml +Type: Hashtable +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Collections.Hashtable[] + +## OUTPUTS + +### PSDepend.Dependency + +## NOTES + +## RELATED LINKS + +[Invoke-PSDepend](Invoke-PSDepend.md) diff --git a/docs/en-US/Get-PSDependScript.md b/docs/en-US/Get-PSDependScript.md new file mode 100644 index 0000000..cc25e32 --- /dev/null +++ b/docs/en-US/Get-PSDependScript.md @@ -0,0 +1,78 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Get-PSDependScript + +## SYNOPSIS + +Get dependency type scripts registered in PSDepend. + +## SYNTAX + +``` +Get-PSDependScript [[-Path] ] [-ProgressAction ] [] +``` + +## DESCRIPTION + +Returns the scripts associated with each registered dependency type from PSDependMap.psd1. + +## EXAMPLES + +### Example 1 + +```powershell +Get-PSDependScript +``` + +Returns all dependency type scripts from the default PSDependMap.psd1. + +## PARAMETERS + +### -Path + +Path to a PSDependMap.psd1 file. Defaults to the one in the PSDepend module root. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Get-PSDependType](Get-PSDependType.md) diff --git a/docs/en-US/Get-PSDependType.md b/docs/en-US/Get-PSDependType.md new file mode 100644 index 0000000..d2395df --- /dev/null +++ b/docs/en-US/Get-PSDependType.md @@ -0,0 +1,136 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Get-PSDependType + +## SYNOPSIS + +Get dependency types and related information. + +## SYNTAX + +``` +Get-PSDependType [[-DependencyType] ] [[-Path] ] [-ShowHelp] [-SkipHelp] + [-ProgressAction ] [] +``` + +## DESCRIPTION + +Returns information about registered PSDepend dependency types, optionally showing the +help content for each type's script. + +## EXAMPLES + +### Example 1 + +```powershell +Get-PSDependType +``` + +Returns all registered dependency types. + +### Example 2 + +```powershell +Get-PSDependType -DependencyType PSGalleryModule -ShowHelp +``` + +Returns the PSGalleryModule dependency type and displays its help. + +## PARAMETERS + +### -DependencyType + +Limit results to this dependency type. Accepts wildcards. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path + +Path to a PSDependMap.psd1 file. Defaults to the one in the PSDepend module root. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ShowHelp + +Display help content for the dependency type script. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -SkipHelp + +Skip retrieving help content for dependency type scripts. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Get-PSDependScript](Get-PSDependScript.md) diff --git a/docs/en-US/Import-Dependency.md b/docs/en-US/Import-Dependency.md new file mode 100644 index 0000000..63a8552 --- /dev/null +++ b/docs/en-US/Import-Dependency.md @@ -0,0 +1,116 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Import-Dependency + +## SYNOPSIS + +Import a specific dependency. + +## SYNTAX + +``` +Import-Dependency -Dependency [-PSDependTypePath ] [-Tags ] + [-ProgressAction ] [] +``` + +## DESCRIPTION + +Imports a dependency object returned by Get-Dependency, using the dependency type's +Import action. + +## EXAMPLES + +### Example 1 + +```powershell +Get-Dependency -Path .\requirements.psd1 | Import-Dependency +``` + +Imports all dependencies defined in requirements.psd1. + +## PARAMETERS + +### -Dependency + +A PSDepend.Dependency object from Get-Dependency. + +```yaml +Type: PSObject[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -PSDependTypePath + +Path to a PSDependMap.psd1 file. Defaults to the one in the PSDepend module root. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Tags + +Only import dependencies with the specified tags. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### PSDepend.Dependency + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Get-Dependency](Get-Dependency.md) +[Install-Dependency](Install-Dependency.md) +[Invoke-PSDepend](Invoke-PSDepend.md) diff --git a/docs/en-US/Install-Dependency.md b/docs/en-US/Install-Dependency.md new file mode 100644 index 0000000..188b60c --- /dev/null +++ b/docs/en-US/Install-Dependency.md @@ -0,0 +1,170 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Install-Dependency + +## SYNOPSIS + +Install a specific dependency. + +## SYNTAX + +``` +Install-Dependency [-Dependency] [[-PSDependTypePath] ] [[-Tags] ] [-Force] + [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +Installs a dependency object returned by Get-Dependency, using the dependency type's +Install action. + +## EXAMPLES + +### Example 1 + +```powershell +Get-Dependency -Path .\requirements.psd1 | Install-Dependency +``` + +Installs all dependencies defined in requirements.psd1. + +### Example 2 + +```powershell +Get-Dependency -Path .\requirements.psd1 | Install-Dependency -Force +``` + +Installs all dependencies, bypassing prompts. + +## PARAMETERS + +### -Dependency + +A PSDepend.Dependency object from Get-Dependency. + +```yaml +Type: PSObject[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -PSDependTypePath + +Path to a PSDependMap.psd1 file. Defaults to the one in the PSDepend module root. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: 2 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Tags + +Only install dependencies with the specified tags. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: 3 +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Force installation, skipping interactive prompts. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### PSDepend.Dependency + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Get-Dependency](Get-Dependency.md) +[Import-Dependency](Import-Dependency.md) +[Invoke-PSDepend](Invoke-PSDepend.md) diff --git a/docs/en-US/Invoke-DependencyScript.md b/docs/en-US/Invoke-DependencyScript.md new file mode 100644 index 0000000..00d8c2a --- /dev/null +++ b/docs/en-US/Invoke-DependencyScript.md @@ -0,0 +1,147 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Invoke-DependencyScript + +## SYNOPSIS + +Invoke a dependency type script for a given action. + +## SYNTAX + +``` +Invoke-DependencyScript -Dependency [-PSDependTypePath ] [-PSDependAction ] + [-Tags ] [-Quiet] [-ProgressAction ] [] +``` + +## DESCRIPTION + +Low-level function that invokes the script for a specific dependency type and action +(Test, Install, or Import). Typically called by Invoke-PSDepend rather than directly. + +## EXAMPLES + +### Example 1 + +```powershell +Get-Dependency -Path .\requirements.psd1 | Invoke-DependencyScript -PSDependAction Test +``` + +Tests each dependency in requirements.psd1. + +## PARAMETERS + +### -Dependency + +A PSDepend.Dependency object from Get-Dependency. + +```yaml +Type: PSObject +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -PSDependTypePath + +Path to a PSDependMap.psd1 file. Defaults to the one in the PSDepend module root. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -PSDependAction + +The action to invoke: Test, Install, or Import. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: Install +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Tags + +Only invoke dependencies with the specified tags. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Quiet + +Return $true or $false for Test actions instead of detailed output. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### PSDepend.Dependency + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Get-Dependency](Get-Dependency.md) +[Invoke-PSDepend](Invoke-PSDepend.md) diff --git a/docs/en-US/Invoke-PSDepend.md b/docs/en-US/Invoke-PSDepend.md new file mode 100644 index 0000000..9569f52 --- /dev/null +++ b/docs/en-US/Invoke-PSDepend.md @@ -0,0 +1,340 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Invoke-PSDepend + +## SYNOPSIS + +Install, import, or test dependencies defined in a PSDepend file. + +## SYNTAX + +### installimport-file (Default) +``` +Invoke-PSDepend [[-Path] ] [-PSDependTypePath ] [-Tags ] [-Recurse ] + [-Import] [-Install] [-Force] [-Target ] [-Credentials ] + [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +### test-file +``` +Invoke-PSDepend [[-Path] ] [-PSDependTypePath ] [-Tags ] [-Recurse ] + [-Test] [-Quiet] [-Force] [-Target ] [-ProgressAction ] [-WhatIf] [-Confirm] + [] +``` + +### test-hashtable +``` +Invoke-PSDepend [[-InputObject] ] [-PSDependTypePath ] [-Tags ] [-Test] [-Quiet] + [-Force] [-Target ] [-ProgressAction ] [-WhatIf] [-Confirm] [] +``` + +### installimport-hashtable +``` +Invoke-PSDepend [[-InputObject] ] [-PSDependTypePath ] [-Tags ] [-Import] + [-Install] [-Force] [-Target ] [-Credentials ] [-ProgressAction ] + [-WhatIf] [-Confirm] [] +``` + +## DESCRIPTION + +The primary entry point for PSDepend. Reads a dependency file (or hashtable) and installs, +imports, or tests each dependency using the appropriate dependency type script. + +By default, Invoke-PSDepend installs dependencies. Use -Test to check whether dependencies +are already present, or -Import to import them after installation. + +## EXAMPLES + +### Example 1 + +```powershell +Invoke-PSDepend -Path .\requirements.psd1 +``` + +Installs all dependencies in requirements.psd1. + +### Example 2 + +```powershell +Invoke-PSDepend -Path .\requirements.psd1 -Test -Quiet +``` + +Returns $true if all dependencies are satisfied, $false otherwise. + +### Example 3 + +```powershell +Invoke-PSDepend -Path .\requirements.psd1 -Tags 'CI' -Force +``` + +Installs only dependencies tagged 'CI', bypassing prompts. + +### Example 4 + +```powershell +Invoke-PSDepend -Path . -Recurse -Import +``` + +Recursively finds all dependency files under the current directory and imports them. + +## PARAMETERS + +### -Path + +Path to a dependency file or folder. Defaults to the current directory. + +```yaml +Type: String[] +Parameter Sets: installimport-file, test-file +Aliases: + +Required: False +Position: 1 +Default value: . +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -InputObject + +Treat a hashtable as dependency file contents rather than reading from disk. + +```yaml +Type: Hashtable[] +Parameter Sets: test-hashtable, installimport-hashtable +Aliases: + +Required: False +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -PSDependTypePath + +Path to a PSDependMap.psd1 file. Defaults to the one in the PSDepend module root. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Tags + +Only process dependencies with the specified tags. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Recurse + +Recursively search for dependency files under Path. + +```yaml +Type: Boolean +Parameter Sets: installimport-file, test-file +Aliases: + +Required: False +Position: Named +Default value: True +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Test + +Test whether dependencies are already satisfied instead of installing. + +```yaml +Type: SwitchParameter +Parameter Sets: test-file, test-hashtable +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Quiet + +When used with -Test, return $true or $false instead of detailed objects. + +```yaml +Type: SwitchParameter +Parameter Sets: test-file, test-hashtable +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Import + +Import dependencies after installation, if supported by the dependency type. + +```yaml +Type: SwitchParameter +Parameter Sets: installimport-file, installimport-hashtable +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Install + +Run the install action. This is the default behavior. + +```yaml +Type: SwitchParameter +Parameter Sets: installimport-file, installimport-hashtable +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force + +Force dependency installation, skipping interactive prompts. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Target + +Override the Target property for all dependencies. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Credentials + +Hashtable of PSCredentials keyed by credential name for private feeds. + +```yaml +Type: Hashtable +Parameter Sets: installimport-file, installimport-hashtable +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -WhatIf +Shows what would happen if the cmdlet runs. The cmdlet is not run. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: wi + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Confirm +Prompts you for confirmation before running the cmdlet. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: cf + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### System.Collections.Hashtable[] + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Get-Dependency](Get-Dependency.md) +[Install-Dependency](Install-Dependency.md) +[Import-Dependency](Import-Dependency.md) +[Test-Dependency](Test-Dependency.md) diff --git a/docs/en-US/Test-Dependency.md b/docs/en-US/Test-Dependency.md new file mode 100644 index 0000000..a0dd9d3 --- /dev/null +++ b/docs/en-US/Test-Dependency.md @@ -0,0 +1,140 @@ +--- +external help file: PSDepend-help.xml +Module Name: PSDepend +online version: https://github.com/PowerShellOrg/PSDepend +schema: 2.0.0 +--- + +# Test-Dependency + +## SYNOPSIS + +Test whether a specific dependency is already satisfied. + +## SYNTAX + +``` +Test-Dependency -Dependency [-PSDependTypePath ] [-Tags ] [-Quiet] + [-ProgressAction ] [] +``` + +## DESCRIPTION + +Tests a dependency object returned by Get-Dependency and reports whether it is already +installed or present, using the dependency type's Test action. + +## EXAMPLES + +### Example 1 + +```powershell +Get-Dependency -Path .\requirements.psd1 | Test-Dependency +``` + +Tests all dependencies defined in requirements.psd1. + +### Example 2 + +```powershell +Get-Dependency -Path .\requirements.psd1 | Test-Dependency -Quiet +``` + +Returns $true if all dependencies are satisfied, $false otherwise. + +## PARAMETERS + +### -Dependency + +A PSDepend.Dependency object from Get-Dependency. + +```yaml +Type: PSObject[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: True (ByValue) +Accept wildcard characters: False +``` + +### -PSDependTypePath + +Path to a PSDependMap.psd1 file. Defaults to the one in the PSDepend module root. + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Tags + +Only test dependencies with the specified tags. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Quiet + +Return $true or $false instead of detailed dependency objects. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -ProgressAction +{{ Fill ProgressAction Description }} + +```yaml +Type: ActionPreference +Parameter Sets: (All) +Aliases: proga + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216). + +## INPUTS + +### PSDepend.Dependency + +## OUTPUTS + +## NOTES + +## RELATED LINKS + +[Get-Dependency](Get-Dependency.md) +[Install-Dependency](Install-Dependency.md) +[Invoke-PSDepend](Invoke-PSDepend.md) diff --git a/docs/en-US/about_PSDepend.help.md b/docs/en-US/about_PSDepend.help.md new file mode 100644 index 0000000..c801982 --- /dev/null +++ b/docs/en-US/about_PSDepend.help.md @@ -0,0 +1,97 @@ +# about_PSDepend + +## SHORT DESCRIPTION + +PSDepend is a PowerShell dependency handler that installs, imports, and tests +dependencies defined in .psd1 files. + +## LONG DESCRIPTION + +PSDepend reads dependency files (.psd1) and processes each dependency using a +pluggable set of dependency type scripts. Out of the box it supports: + +- **PSGalleryModule** — Install modules from the PowerShell Gallery +- **PSGalleryNuget** — Install modules from the Gallery without PowerShellGet +- **Git** — Clone Git repositories +- **GitHub** — Download and extract GitHub archives +- **Chocolatey** — Install Chocolatey packages (Windows only) +- **FileDownload** — Download arbitrary files (Windows only) +- **FileSystem** — Copy files or folders (Windows only) +- **Npm** — Install Node.js packages +- **DotnetSdk** — Install the .NET SDK +- **Command** — Run an arbitrary PowerShell command +- **Package** — Install via PackageManagement +- **Task** — Run simple task dependencies +- **Noop** — Display parameters (useful for testing/validation) + +### Dependency File Format + +A dependency file is a PowerShell data file (.psd1) containing a hashtable. The +simplest form uses the key as the dependency name and the value as the version: + +```powershell +@{ + Pester = '5.6.1' + PSScriptAnalyzer = 'latest' +} +``` + +For more control, specify the dependency type and additional properties: + +```powershell +@{ + MyModule = @{ + DependencyType = 'PSGalleryModule' + Version = '1.0.0' + Tags = 'prod' + Target = 'C:\Modules' + } +} +``` + +### PSDependOptions + +Use the special `PSDependOptions` key to set defaults for all dependencies in +the file: + +```powershell +@{ + PSDependOptions = @{ + Target = 'CurrentUser' + AddToPath = $true + } + + Pester = 'latest' +} +``` + +## EXAMPLES + +### Install dependencies from a file + +```powershell +Invoke-PSDepend -Path .\requirements.psd1 -Force +``` + +### Test whether dependencies are satisfied + +```powershell +Invoke-PSDepend -Path .\requirements.psd1 -Test -Quiet +``` + +### Install and immediately import + +```powershell +Invoke-PSDepend -Path .\requirements.psd1 -Install -Import -Force +``` + +## NOTE + +Custom dependency types can be registered by adding entries to a custom +PSDependMap.psd1 and passing its path via `-PSDependTypePath`. + +## SEE ALSO + +- [Invoke-PSDepend](Invoke-PSDepend.md) +- [Get-PSDependType](Get-PSDependType.md) +- PSDepend project: https://github.com/PowerShellOrg/PSDepend diff --git a/psake.ps1 b/psake.ps1 deleted file mode 100644 index c166dfa..0000000 --- a/psake.ps1 +++ /dev/null @@ -1,120 +0,0 @@ -# PSake makes variables declared here available in other scriptblocks -# Init some things -Properties { - # Find the build folder based on build system - $ProjectRoot = $ENV:BHProjectPath - if(-not $ProjectRoot) - { - $ProjectRoot = $PSScriptRoot - } - $ProjectRoot = Convert-Path $ProjectRoot - - try { - $script:IsWindows = (-not (Get-Variable -Name IsWindows -ErrorAction Ignore)) -or $IsWindows - $script:IsLinux = (Get-Variable -Name IsLinux -ErrorAction Ignore) -and $IsLinux - $script:IsMacOS = (Get-Variable -Name IsMacOS -ErrorAction Ignore) -and $IsMacOS - $script:IsCoreCLR = $PSVersionTable.ContainsKey('PSEdition') -and $PSVersionTable.PSEdition -eq 'Core' - } - catch { } - - $Timestamp = Get-date -uformat "%Y%m%d-%H%M%S" - $PSVersion = $PSVersionTable.PSVersion.Major - $TestFile = "TestResults_PS$PSVersion`_$TimeStamp.xml" - $lines = '----------------------------------------------------------------------' - - $Verbose = @{} - if($ENV:BHCommitMessage -match "!verbose") - { - $Verbose = @{Verbose = $True} - } -} - -Task Default -Depends Deploy - -Task Init { - $lines - Set-Location $ProjectRoot - "Build System Details:" - Get-Item ENV:BH* - "`n" -} - -Task Test -Depends Init { - $lines - "`n`tSTATUS: Testing with PowerShell $PSVersion" - - # Gather test results. Store them in a variable and file - $pesterParameters = @{ - Path = "$ProjectRoot\Tests" - PassThru = $true - OutputFormat = "NUnitXml" - OutputFile = "$ProjectRoot\$TestFile" - } - if (-Not $IsWindows) { $pesterParameters["ExcludeTag"] = "WindowsOnly" } - $TestResults = Invoke-Pester @pesterParameters - - # In Appveyor? Upload our tests! #Abstract this into a function? - If($ENV:BHBuildSystem -eq 'AppVeyor') - { - (New-Object 'System.Net.WebClient').UploadFile( - "https://ci.appveyor.com/api/testresults/nunit/$($env:APPVEYOR_JOB_ID)", - "$ProjectRoot\$TestFile" ) - } - - Remove-Item "$ProjectRoot\$TestFile" -Force -ErrorAction SilentlyContinue - - # Failed tests? - # Need to tell psake or it will proceed to the deployment. Danger! - if($TestResults.FailedCount -gt 0) - { - Write-Error "Failed '$($TestResults.FailedCount)' tests, build failed" - } - "`n" -} - -Task Build -Depends Test { - $lines - - # Load the module, read the exported functions, update the psd1 FunctionsToExport - Set-ModuleFunctions - - # Bump the module version if we didn't already - Try - { - [version]$GalleryVersion = Get-NextNugetPackageVersion -Name $env:BHProjectName -ErrorAction Stop - [version]$GithubVersion = Get-MetaData -Path $env:BHPSModuleManifest -PropertyName ModuleVersion -ErrorAction Stop - if($GalleryVersion -ge $GithubVersion) { - Update-Metadata -Path $env:BHPSModuleManifest -PropertyName ModuleVersion -Value $GalleryVersion -ErrorAction stop - } - } - Catch - { - "Failed to update version for '$env:BHProjectName': $_.`nContinuing with existing version" - } -} - -Task Deploy -Depends Build { - $lines - - # Gate deployment - if( - $ENV:BHBuildSystem -ne 'Unknown' -and - $ENV:BHBranchName -eq "master" -and - $ENV:BHCommitMessage -match '!deploy' - ) - { - $Params = @{ - Path = $ProjectRoot - Force = $true - } - - Invoke-PSDeploy @Verbose @Params - } - else - { - "Skipping deployment: To deploy, ensure that...`n" + - "`t* You are in a known build system (Current: $ENV:BHBuildSystem)`n" + - "`t* You are committing to the master branch (Current: $ENV:BHBranchName) `n" + - "`t* Your commit message includes !deploy (Current: $ENV:BHCommitMessage)" - } -} diff --git a/psakeFile.ps1 b/psakeFile.ps1 new file mode 100644 index 0000000..202a4e7 --- /dev/null +++ b/psakeFile.ps1 @@ -0,0 +1,36 @@ +properties { + # PSDepend stages files without compiling to a single PSM1 + $PSBPreference.Build.CompileModule = $false + + # Help generation + $PSBPreference.Help.DefaultLocale = 'en-US' + + # Extra subdirectories beyond Public/Private that must be staged + $PSBPreference.Build.CopyDirectories = @('PSDependScripts', 'en-US') + + # Test configuration + $PSBPreference.Test.OutputFile = './Output/testResults.xml' + $PSBPreference.Test.OutputFormat = 'JUnitXml' + $PSBPreference.Test.ScriptAnalysis.Enabled = $true + $PSBPreference.Test.ScriptAnalysis.FailBuildOnSeverityLevel = 'Error' + $PSBPreference.Test.CodeCoverage.Enabled = $false + + # Exclude Windows-only tests on non-Windows runners + if (-not $IsWindows) { + $PSBPreference.Test.ExcludeTagFilter = @('WindowsOnly') + } + + # Publish configuration — API key injected via environment in CI + $PSBPreference.Publish.PSRepository = 'PSGallery' + $PSBPreference.Publish.PSRepositoryApiKey = $env:PSGALLERY_API_KEY +} + +task default -depends Test + +task Init -FromModule PowerShellBuild -minimumVersion '0.6.1' +task Clean -FromModule PowerShellBuild -minimumVersion '0.6.1' +task Build -FromModule PowerShellBuild -minimumVersion '0.6.1' +task Analyze -FromModule PowerShellBuild -minimumVersion '0.6.1' +task Pester -FromModule PowerShellBuild -minimumVersion '0.6.1' +task Test -FromModule PowerShellBuild -minimumVersion '0.6.1' +task Publish -FromModule PowerShellBuild -minimumVersion '0.6.1' diff --git a/requirements.psd1 b/requirements.psd1 new file mode 100644 index 0000000..51f85ad --- /dev/null +++ b/requirements.psd1 @@ -0,0 +1,23 @@ +@{ + PSDependOptions = @{ + Target = 'CurrentUser' + } + 'psake' = @{ + Version = '4.9.1' + } + 'PowerShellBuild' = @{ + Version = '0.7.2' + } + 'Pester' = @{ + Version = '5.7.1' + Parameters = @{ + SkipPublisherCheck = $true + } + } + 'PSScriptAnalyzer' = @{ + Version = '1.19.1' + } + 'BuildHelpers' = @{ + Version = '2.0.16' + } +}