Add Get-VSTeamGitStats

.docs/Get-VSTeamGitStats.md

@@ -0,0 +1,104 @@
+<!-- #include "./common/header.md" -->
+
+# Get-VSTeamGitStats
+
+## SYNOPSIS
+
+<!-- #include "./synopsis/Get-VSTeamGitStats.md" -->
+
+## SYNTAX
+
+## DESCRIPTION
+
+Get-VSTeamGitStats retrieves statistics about branches within a repository.
+
+## EXAMPLES
+
+### -------------------------- EXAMPLE 1 --------------------------
+
+```PowerShell
+PS C:\> Get-VSTeamGitStats -ProjectName Demo -RepositoryId 011E421A-2A54-4491-B370-9256AD8A1BDD
+```
+
+### -------------------------- EXAMPLE 2 --------------------------
+
+```PowerShell
+PS C:\> Get-VSTeamGitStats -ProjectName Demo -RepositoryId 011E421A-2A54-4491-B370-9256AD8A1BDD -BranchName develop
+```
+
+This command returns all the Git stats for a specific branch
+
+### -------------------------- EXAMPLE 3 --------------------------
+
+```PowerShell
+PS C:\> Get-VSTeamGitStats -ProjectName Demo -RepositoryId 011E421A-2A54-4491-B370-9256AD8A1BDD -BranchName develop -VersionType branch -Version 67cae2b029dff7eb3dc062b49403aaedca5bad8d
+```
+
+This command returns all the Git stats for a specific commit
+
+## PARAMETERS
+
+<!-- #include "./params/projectName.md" -->
+
+### -RepositoryId
+
+Specifies the ID of the repository.
+
+```yaml
+Type: Guid
+Aliases: ID
+Required: true
+Accept pipeline input: true (ByPropertyName)
+```
+
+### -BranchName
+
+Name of the branch.
+
+```yaml
+Type: String
+Required: true
+```
+
+### -VersionOptions
+
+Version options - Specify additional modifiers to version (e.g Previous). Valid options for this parameter are:
+
+- firstParent
+- none
+- previousChange
+
+```yaml
+Type: String
+Parameter Sets: ByVersion
+```
+
+### -Version
+
+Version string identifier (name of tag/branch, SHA1 of commit)
+
+```yaml
+Type: String
+Parameter Sets: ByVersion
+```
+
+### -VersionType
+
+Version type (branch, tag, or commit). Determines how Id is interpreted. Valid options for this parameter are:
+
+- branch
+- commit
+- tag
+
+```yaml
+Type: String
+Parameter Sets: ByVersion
+```
+
+## INPUTS
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS

.docs/synopsis/Get-VSTeamGitStats.md

@@ -0,0 +1 @@
+Get-VSTeamGitStats retrieves statistics about branches within a repository.

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 6.4.5
+
+Merged [Pull Request](https://github.com/DarqueWarrior/vsteam/pull/245) from [Michel Zehnder](https://github.com/MichelZ) which included the following:
+
+Add Get-VSTeamGitStats to retrieve statistics about branches
+
 ## 6.4.4
 
 Merged [Pull Request](https://github.com/DarqueWarrior/vsteam/pull/231) from [Dave Neeley](https://github.com/daveneeley) which included the following:

Source/Public/Get-VSTeamGitStats.ps1

@@ -0,0 +1,67 @@
+function Get-VSTeamGitStats {
+   [CmdletBinding(DefaultParameterSetName = "ByOptionalName")]
+   param (
+      [Parameter(ParameterSetName = "ByVersion", ValueFromPipelineByPropertyName = $true, Mandatory = $true)]
+      [Parameter(ParameterSetName = "ByOptionalName", ValueFromPipelineByPropertyName = $true, Mandatory = $true)]
+      [Alias('Id')]
+      [guid] $RepositoryId,
+
+      [Parameter(ParameterSetName = 'ByVersion', Mandatory = $false)]
+      [Parameter(ParameterSetName = 'ByOptionalName', Mandatory = $false)]
+      [string] $BranchName,
+
+      [ValidateSet("firstParent", "none", "previousChange")]
+      [Parameter(ParameterSetName = 'ByVersion', Mandatory = $false)]
+      [string] $VersionOptions,
+
+      [Parameter(ParameterSetName = 'ByVersion', Mandatory = $true)]
+      [string] $Version,
+
+      [Parameter(ParameterSetName = 'ByVersion', Mandatory = $true)]
+      [ValidateSet("branch", "commit", "tag")]
+      [string] $VersionType
+   )
+
+   DynamicParam {
+      _buildProjectNameDynamicParam -Mandatory $true
+   }
+
+   process {
+      # Bind the parameter to a friendly variable
+      $ProjectName = $PSBoundParameters["ProjectName"]
+
+      if (($VersionType -eq "commit") -and ($Version -eq $null -or $Version -eq ''))
+      {
+         throw "If you have a -VersionType of 'commit' you need to set a commit id as -Version";
+      }
+
+      try {
+         $queryString = @{
+            'name'                                 = $BranchName
+            'baseVersionDescriptor.versionType'    = $VersionType
+            'baseVersionDescriptor.version'        = $Version
+            'baseVersionDescriptor.versionOptions' = $VersionOptions
+         }
+
+         $resp = _callAPI -ProjectName $ProjectName -Id "$RepositoryID/stats/branches" -Area git -Resource repositories -Version $([VSTeamVersions]::Git) -QueryString $queryString
+
+         $hasValueProp = $resp.PSObject.Properties.Match('value')
+
+         if (0 -eq $hasValueProp.count) {
+            _applyTypes $resp "VSTeam.GitStats"
+            Write-Output $resp
+         } else {
+            $obj = @()
+            foreach ($item in $resp.value) {
+               _applyTypes $item "VSTeam.GitStats"
+               $obj += $item
+            }
+
+            Write-Output $obj
+         }
+      }
+      catch {
+         throw $_
+      }
+   }
+}

Source/VSTeam.psd1

@@ -12,7 +12,7 @@
    RootModule        = 'VSTeam.psm1'
 
    # Version number of this module.
-   ModuleVersion     = '6.4.4'
+   ModuleVersion     = '6.4.5'
 
    # Supported PSEditions
    # CompatiblePSEditions = @()
@@ -27,7 +27,7 @@
    CompanyName       = ''
 
    # Copyright statement for this module
-   Copyright         = '(c) 2019 Donovan Brown. All rights reserved.'
+   Copyright         = '(c) 2020 Donovan Brown. All rights reserved.'
 
    # Description of the functionality provided by this module
    Description       = 'Adds functionality for working with Azure DevOps and Team Foundation Server.'

unit/test/Get-VSTeamGitStats.Tests.ps1

@@ -0,0 +1,186 @@
+Set-StrictMode -Version Latest
+
+InModuleScope VSTeam {
+
+   # Set the account to use for testing. A normal user would do this
+   # using the Set-VSTeamAccount function.
+   [VSTeamVersions]::Account = 'https://dev.azure.com/test'
+
+   $singleResult = [PSCustomObject]@{
+      commit = [PSCustomObject]@{
+         commitId = '67cae2b029dff7eb3dc062b49403aaedca5bad8d'
+         author = [PSCustomObject]@{
+            name = '"Chuck Reinhart'
+            email = '[email protected]'
+            date = '2014-01-29T23:52:56Z'
+         }
+         committer = [PSCustomObject]@{
+            name = '"Chuck Reinhart'
+            email = '[email protected]'
+            date = '2014-01-29T23:52:56Z'
+         }
+         comment = 'home page'
+         url = 'https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/67cae2b029dff7eb3dc062b49403aaedca5bad8d'
+      }
+      name = 'develop'
+      aheadCount = 1
+      behindCount = 17
+      isBaseVersion = $false
+   }
+
+   $multipleResults = [PSCustomObject]@{
+      count = 3
+      value = @(
+         [PSCustomObject]@{
+            commit = [PSCustomObject]@{
+               commitId = '67cae2b029dff7eb3dc062b49403aaedca5bad8d'
+               author = [PSCustomObject]@{
+                  name = '"Chuck Reinhart'
+                  email = '[email protected]'
+                  date = '2014-01-29T23:52:56Z'
+               }
+               committer = [PSCustomObject]@{
+                  name = '"Chuck Reinhart'
+                  email = '[email protected]'
+                  date = '2014-01-29T23:52:56Z'
+               }
+               comment = 'home page'
+               url = 'https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/67cae2b029dff7eb3dc062b49403aaedca5bad8d'
+            }
+            name = 'develop'
+            aheadCount = 1
+            behindCount = 17
+            isBaseVersion = $false
+         },
+         [PSCustomObject]@{
+            commit = [PSCustomObject]@{
+               parents = @('fe17a84cc2dfe0ea3a2202ab4dbac0706058e41f')
+               treeId = '8263e7232a2331c563d737e4fc4e9c66a8286c63'
+               commitId = '23d0bc5b128a10056dc68afece360d8a0fabb014'
+               author = [PSCustomObject]@{
+                  name = 'Norman Paulk'
+                  email = '[email protected]'
+                  date = '2014-06-30T18:10:55Z'
+               }
+               committer = [PSCustomObject]@{
+                  name = 'Norman Paulk'
+                  email = '[email protected]'
+                  date = '2014-06-30T18:10:55Z'
+               }
+               comment = 'Better description for hello world\n'
+               url = 'https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/23d0bc5b128a10056dc68afece360d8a0fabb014'
+            }
+            name = 'master'
+            aheadCount = 0
+            behindCount = 0
+            isBaseVersion = $true
+         },
+         [PSCustomObject]@{
+            commit = [PSCustomObject]@{
+               parents = @('fe17a84cc2dfe0ea3a2202ab4dbac0706058e41f')
+               treeId = '8263e7232a2331c563d737e4fc4e9c66a8286c63'
+               commitId = '23d0bc5b128a10056dc68afece360d8a0fabb014'
+               author = [PSCustomObject]@{
+                  name = 'Norman Paulk'
+                  email = '[email protected]'
+                  date = '2014-06-30T18:10:55Z'
+               }
+               committer = [PSCustomObject]@{
+                  name = 'Norman Paulk'
+                  email = '[email protected]'
+                  date = '2014-06-30T18:10:55Z'
+               }
+               comment = 'Better description for hello world\n'
+               url = 'https://dev.azure.com/fabrikam/_apis/git/repositories/278d5cd2-584d-4b63-824a-2ba458937249/commits/23d0bc5b128a10056dc68afece360d8a0fabb014'
+            }
+            name = 'npaulk/feature'
+            aheadCount = 0
+            behindCount = 0
+            isBaseVersion = $true
+         }
+      )
+   }
+
+   Describe "Git VSTS" {
+      # Mock the call to Get-Projects by the dynamic parameter for ProjectName
+      Mock Invoke-RestMethod { return @() } -ParameterFilter {
+         $Uri -like "*_apis/projects*"
+      }
+
+      . "$PSScriptRoot\mocks\mockProjectNameDynamicParam.ps1"
+
+      Context 'Get-VSTeamGitStats' {
+         Mock Invoke-RestMethod { return $multipleResults } -Verifiable -ParameterFilter {
+            $Uri -like "*/Test/*" -and
+            $Uri -like "*repositories/00000000-0000-0000-0000-000000000000/stats/branches*"
+         }
+
+         Get-VSTeamGitStats -ProjectName Test -RepositoryId 00000000-0000-0000-0000-000000000000
+
+         It 'Should return multiple results' {
+            Assert-VerifiableMock
+         }
+      }
+
+      Context 'Get-VSTeamGitStats by name' {
+         Mock Invoke-RestMethod { return $singleResult } -Verifiable -ParameterFilter {
+            $Uri -like "*/Test/*" -and
+            $Uri -like "*repositories/00000000-0000-0000-0000-000000000000/stats/branches*" -and
+            $Uri -like "*name=develop*"
+         }
+
+         Get-VSTeamGitStats -ProjectName Test -RepositoryId 00000000-0000-0000-0000-000000000000 -BranchName develop
+
+         It 'Should return multiple results' {
+            Assert-VerifiableMock
+         }
+      }
+
+      Context 'Get-VSTeamGitStats by tag' {
+         Mock Invoke-RestMethod { return $singleResult } -Verifiable -ParameterFilter {
+            $Uri -like "*/Test/*" -and
+            $Uri -like "*repositories/00000000-0000-0000-0000-000000000000/stats/branches*" -and
+            $Uri -like "*baseVersionDescriptor.versionType=tag*" -and
+            $Uri -like "*baseVersionDescriptor.version=test*"
+         }
+
+         Get-VSTeamGitStats -ProjectName Test -RepositoryId 00000000-0000-0000-0000-000000000000 -BranchName "develop" -VersionType "tag" -Version "test"
+
+         It 'Should return multiple results' {
+            Assert-VerifiableMock
+         }
+      }
+
+      Context 'Get-VSTeamGitStats by tag with options' {
+         Mock Invoke-RestMethod { return $singleResult } -Verifiable -ParameterFilter {
+            $Uri -like "*/Test/*" -and
+            $Uri -like "*repositories/00000000-0000-0000-0000-000000000000/stats/branches*" -and
+            $Uri -like "*baseVersionDescriptor.versionType=tag*" -and
+            $Uri -like "*baseVersionDescriptor.version=test*" -and
+            $Uri -like "*baseVersionDescriptor.versionOptions=previousChange*"
+         }
+
+         Get-VSTeamGitStats -ProjectName Test -RepositoryId 00000000-0000-0000-0000-000000000000 -BranchName "develop" -VersionType "tag" -Version "test" -VersionOptions previousChange
+
+         It 'Should return multiple results' {
+            Assert-VerifiableMock
+         }
+      }
+
+      Context 'Get-VSTeamGitStats by commit throws' {
+         Mock Invoke-RestMethod { return $singleResult }
+
+         It 'Should throw because of invalid parameters' {
+            { Get-VSTeamGitStats -ProjectName Test -RepositoryId 00000000-0000-0000-0000-000000000000 -VersionType commit -Version '' } | Should Throw
+         }
+      }
+
+      Context 'Get-VSTeamGitStats by id throws' {
+         Mock Invoke-RestMethod { throw [System.Net.WebException] "Test Exception." }
+
+         It 'Should return a single repo by id' {
+            { Get-VSTeamGitStats -ProjectName Test -RepositoryId 00000000-0000-0000-0000-000000000000 } | Should Throw
+         }
+      }
+   }
+}