docs: Cleanup and consistency (#93)

.github/ISSUE_TEMPLATE/Bug.md

@@ -1,6 +1,6 @@
 ---
 name: Bug
-about: A problem which makes it impossible to use Scoop.
+about: A problem which makes it impossible to use Shovel.
 labels: bug
 ---
 

.github/ISSUE_TEMPLATE/Enhancement.md

@@ -1,7 +1,7 @@
 ---
 name: Enhancement
-about: Some feature, idea or enhancement to improve Scoop.
+about: Some feature, idea or enhancement to improve Shovel.
 labels: enhancement
 ---
 
-<!-- Describe your feature, idea or enhancement about how to improve Scoop. -->
+<!-- Describe your feature, idea or enhancement about how to improve Shovel. -->

bin/auto-pr.ps1

@@ -4,23 +4,23 @@
 .DESCRIPTION
     Updates manifests and pushes them directly to the master branch or creates pull-requests for upstream.
 .PARAMETER Upstream
-    Upstream repository with the target branch.
+    Specifies the upstream repository with the target branch.
     Must be in format '<user>/<repo>:<branch>'
 .PARAMETER App
-    Manifest name to search.
-    Placeholders are supported.
+    Specifies the manifest name to search.
+    Wildcards are supported.
 .PARAMETER Dir
-    The directory where to search for manifests.
+    Specifies the location of manifests.
 .PARAMETER Push
-    Push updates directly to 'origin master'.
+    Specifies to push updates directly to 'origin master'.
 .PARAMETER Request
-    Create pull-requests on 'upstream master' for each update.
+    Specifies to create pull-requests on 'upstream master' for each update instead of direct pushing.
 .PARAMETER Help
-    Print help to console.
+    Specifies to print help to console.
 .PARAMETER SpecialSnowflakes
-    An array of manifests, which should be updated all the time. (-ForceUpdate parameter to checkver)
+    Specifies an array of manifest names, which should be updated all the time. (-ForceUpdate parameter to checkver)
 .PARAMETER SkipUpdated
-    Updated manifests will not be shown.
+    Specifies to not show up-to-date manifests.
 .PARAMETER SkipCheckver
     Specifies to skip checkver execution.
 .EXAMPLE
@@ -29,25 +29,24 @@
     PS BUCKETROOT > .\bin\auto-pr.ps1 -Push
     Update all manifests inside 'bucket/' directory.
 #>
-
 param(
-    [Parameter(Mandatory = $true)]
+    [Parameter(Mandatory)]
     [ValidateScript( {
-        if (!($_ -match '^(.*)\/(.*):(.*)$')) { throw 'Upstream must be in this format: <user>/<repo>:<branch>' }
-        $true
-    })]
+            if ($_ -notmatch '^(.*)\/(.*):(.*)$') { throw 'Upstream must be in format: <user>/<repo>:<branch>' }
+            $true
+        })]
     [String] $Upstream,
     [String] $App = '*',
-    [Parameter(Mandatory = $true)]
+    [Parameter(Mandatory)]
     [ValidateScript( {
-        if (!(Test-Path $_ -Type Container)) { throw "$_ is not a directory!" }
-        $true
-    })]
+            if (!(Test-Path $_ -Type 'Container')) { throw "$_ is not a directory!" }
+            $true
+        })]
     [String] $Dir,
     [Switch] $Push,
     [Switch] $Request,
     [Switch] $Help,
-    [string[]] $SpecialSnowflakes,
+    [String[]] $SpecialSnowflakes,
     [Switch] $SkipUpdated,
     [Switch] $SkipCheckver
 )
@@ -60,23 +59,23 @@ $Upstream | Out-Null # PowerShell/PSScriptAnalyzer#1472
 
 $Dir = Resolve-Path $Dir
 
-if ((!$Push -and !$Request) -or $Help) {
-    Write-Host @'
+if ($Help -or (!$Push -and !$Request)) {
+    Write-UserMessage @'
 Usage: auto-pr.ps1 [OPTION]
 
 Mandatory options:
-  -p,  -push                       push updates directly to 'origin master'
-  -r,  -request                    create pull-requests on 'upstream master' for each update
+  -p,  -push                Push updates directly to 'origin master'
+  -r,  -request             Create pull-requests on 'upstream master' for each update
 
 Optional options:
-  -u,  -upstream                   upstream repository with target branch
-                                   only used if -r is set (default: lukesampson/scoop:master)
+  -u,  -upstream            Upstream repository with target branch
+                            Only used if -r is set (default: lukesampson/scoop:master)
   -h,  -help
 '@
     exit 0
 }
 
-if (!(Get-Command -Name 'hub' -CommandType Application -ErrorAction SilentlyContinue)) {
+if (!(Get-Command -Name 'hub' -CommandType 'Application' -ErrorAction 'SilentlyContinue')) {
     Stop-ScoopExecution -Message 'hub is required! Please refer to ''https://hub.github.com/'' to find out how to get hub for your platform.'
 }
 
@@ -89,25 +88,26 @@ function execute($cmd) {
     return $output
 }
 
+# json object, application name, upstream repository, relative path to manifest file
 function pull_requests($json, [String] $app, [String] $upstream, [String] $manifest) {
     $version = $json.version
     $homepage = $json.homepage
     $branch = "manifest/$app-$version"
 
     execute 'hub checkout master'
-    Write-Host "hub rev-parse --verify $branch" -ForegroundColor Green
+    Write-UserMessage "hub rev-parse --verify $branch" -ForegroundColor 'Green'
     hub rev-parse --verify $branch
 
     if ($LASTEXITCODE -eq 0) {
-        Write-Host "Skipping update $app ($version) ..." -ForegroundColor Yellow
+        Write-UserMessage "Skipping update $app ($version) ..." -ForegroundColor 'Yellow'
         return
     }
 
-    Write-Host "Creating update $app ($version) ..." -ForegroundColor DarkCyan
+    Write-UserMessage "Creating update $app ($version) ..." -ForegroundColor 'DarkCyan'
     execute "hub checkout -b $branch"
     execute "hub add $manifest"
     execute "hub commit -m '${app}: Update to version $version'"
-    Write-Host "Pushing update $app ($version) ..." -ForegroundColor DarkCyan
+    Write-UserMessage "Pushing update $app ($version) ..." -ForegroundColor 'DarkCyan'
     execute "hub push origin $branch"
 
     if ($LASTEXITCODE -gt 0) {
@@ -116,12 +116,12 @@ function pull_requests($json, [String] $app, [String] $upstream, [String] $manif
         return
     }
 
-    Start-Sleep 1
-    Write-Host "Pull-Request update $app ($version) ..." -ForegroundColor DarkCyan
-    Write-Host "hub pull-request -m '<msg>' -b '$upstream' -h '$branch'" -ForegroundColor Green
+    Start-Sleep -Seconds 1
+    Write-UserMessage "Pull-Request update $app ($version) ..." -ForegroundColor 'DarkCyan'
+    Write-UserMessage "hub pull-request -m '<msg>' -b '$upstream' -h '$branch'" -ForegroundColor 'Green'
 
     $msg = @"
-$app`: Update to version $version
+${app}: Update to version $version
 
 Hello lovely humans,
 a new version of [$app]($homepage) is available.
@@ -138,7 +138,7 @@ a new version of [$app]($homepage) is available.
     }
 }
 
-Write-Host 'Updating ...' -ForegroundColor DarkCyan
+Write-UserMessage 'Updating ...' -ForegroundColor 'DarkCyan'
 if ($Push) {
     execute 'hub pull origin master'
     execute 'hub checkout master'
@@ -148,11 +148,11 @@ if ($Push) {
 }
 
 if (!$SkipCheckver) {
-    . "$PSScriptRoot\checkver.ps1" -App $App -Dir $Dir -Update -SkipUpdated:$SkipUpdated
+    & "$PSScriptRoot\checkver.ps1" -App $App -Dir $Dir -Update -SkipUpdated:$SkipUpdated
     if ($SpecialSnowflakes) {
-        Write-UserMessage -Message "Forcing update on our special snowflakes: $($SpecialSnowflakes -join ',')" -Color DarkCyan
+        Write-UserMessage -Message "Forcing update on special snowflakes: $($SpecialSnowflakes -join ',')" -Color 'DarkCyan'
         $SpecialSnowflakes -split ',' | ForEach-Object {
-            . "$PSScriptRoot\checkver.ps1" $_ -Dir $Dir -ForceUpdate
+            & "$PSScriptRoot\checkver.ps1" $_ -Dir $Dir -ForceUpdate
         }
     }
 }
@@ -170,27 +170,27 @@ hub diff --name-only | ForEach-Object {
     $version = $json.version
 
     if ($Push) {
-        Write-Host "Creating update $app ($version) ..." -ForegroundColor DarkCyan
+        Write-UserMessage "Creating update $app ($version) ..." -ForegroundColor 'DarkCyan'
         execute "hub add $manifest"
 
-        # detect if file was staged, because it's not when only LF or CRLF have changed
+        # Detect if file was staged, because it's not when only LF or CRLF have changed
         $status = execute 'hub status --porcelain -uno'
         $status = $status | Where-Object { $_ -match "M\s{2}.*$app.json" }
         if ($status -and $status.StartsWith('M  ') -and $status.EndsWith("$app.json")) {
             execute "hub commit -m '${app}: Update to version $version'"
         } else {
-            Write-Host "Skipping $app because only LF/CRLF changes were detected ..." -ForegroundColor Yellow
+            Write-UserMessage "Skipping $app because only LF/CRLF changes were detected ..." -Info
         }
     } else {
         pull_requests $json $app $Upstream $manifest
     }
 }
 
 if ($Push) {
-    Write-Host 'Pushing updates ...' -ForegroundColor DarkCyan
+    Write-UserMessage 'Pushing updates ...' -ForegroundColor 'DarkCyan'
     execute 'hub push origin master'
 } else {
-    Write-Host 'Returning to master branch and removing unstaged files ...' -ForegroundColor DarkCyan
+    Write-UserMessage 'Returning to master branch and removing unstaged files ...' -ForegroundColor 'DarkCyan'
     execute 'hub checkout -f master'
 }
 

bin/checkhashes.ps1

@@ -1,19 +1,19 @@
 <#
 .SYNOPSIS
-    Check if ALL urls inside manifest have correct hashes.
+    Check if all urls defined in manifest have correct hashes.
 .PARAMETER App
-    Manifest to be checked.
+    Specifies the manifest name to be checked (without extension).
     Wildcards are supported.
 .PARAMETER Dir
-    Where to search for manifest(s).
+    Specifies the location of manifests.
 .PARAMETER Update
-    When there are mismatched hashes, manifest will be updated.
+    Specifies to update the manifest file with updated hashes.
 .PARAMETER ForceUpdate
-    Manifest will be updated all the time. Not only when there are mismatched hashes.
+    Specifies to update the manifest file even without hashes were not changed.
 .PARAMETER SkipCorrect
-    Manifests without mismatch will not be shown.
+    Specifies to not show manifest without mismatched hashes.
 .PARAMETER UseCache
-    Downloaded files will not be deleted after script finish.
+    Specifies to not delete downloaded files from cache.
     Should not be used, because check should be used for downloading actual version of file (as normal user, not finding in some document from vendors, which could be damaged / wrong (Example: Slack@3.3.1 lukesampson/scoop-extras#1192)), not some previously downloaded.
 .EXAMPLE
     PS BUCKETROOT> .\bin\checkhashes.ps1
@@ -25,11 +25,11 @@
 param(
     [SupportsWildcards()]
     [String] $App = '*',
-    [Parameter(Mandatory = $true)]
+    [Parameter(Mandatory)]
     [ValidateScript( {
-        if (!(Test-Path $_ -Type Container)) { throw "$_ is not a directory!" }
-        $true
-    })]
+            if (!(Test-Path $_ -Type 'Container')) { throw "$_ is not a directory!" }
+            $true
+        })]
     [String] $Dir,
     [Switch] $Update,
     [Switch] $ForceUpdate,
@@ -45,11 +45,10 @@ param(
 $Dir = Resolve-Path $Dir
 if ($ForceUpdate) { $Update = $true }
 # Cleanup
-if (!$UseCache) { Join-Path $SCOOP_CACHE_DIRECTORY '*HASH_CHECK*' | Remove-Item -ErrorAction SilentlyContinue -Force -Recurse }
+if (!$UseCache) { Join-Path $SCOOP_CACHE_DIRECTORY '*HASH_CHECK*' | Remove-Item -ErrorAction 'SilentlyContinue' -Force -Recurse }
 
 function err ([String] $name, [String[]] $message) {
-    Write-Host "$name`: " -ForegroundColor Red -NoNewline
-    Write-Host ($message -join "`r`n") -ForegroundColor Red
+    Write-UserMessage "${name}: ", ($message -join "`r`n") -Color 'Red'
 }
 
 $MANIFESTS = @()
@@ -91,9 +90,6 @@ foreach ($single in Get-ChildItem $Dir "$App.*" -File) {
     }
 }
 
-# Clear any existing events
-Get-Event | ForEach-Object { Remove-Event $_.SourceIdentifier }
-
 foreach ($current in $MANIFESTS) {
     $count = 0
     # Array of indexes mismatched hashes.
@@ -134,27 +130,27 @@ foreach ($current in $MANIFESTS) {
     if ($mismatched.Length -eq 0 ) {
         if (!$SkipCorrect) {
             Write-Host "$($current.app): " -NoNewline
-            Write-Host 'OK' -ForegroundColor Green
+            Write-Host 'OK' -ForegroundColor 'Green'
         }
     } else {
         Write-Host "$($current.app): " -NoNewline
-        Write-Host 'Mismatch found ' -ForegroundColor Red
+        Write-Host 'Mismatch found ' -ForegroundColor 'Red'
         $mismatched | ForEach-Object {
             $file = cache_path $current.app $version $current.urls[$_]
             Write-UserMessage -Message "`tURL:`t`t$($current.urls[$_])"
             if (Test-Path $file) {
                 Write-UserMessage -Message "`tFirst bytes:`t$(Get-MagicByte -File $file -Pretty)"
             }
-            Write-UserMessage -Message "`tExpected:`t$($current.hashes[$_])" -Color Green
-            Write-UserMessage -Message "`tActual:`t`t$($actuals[$_])" -Color Red
+            Write-UserMessage -Message "`tExpected:`t$($current.hashes[$_])" -Color 'Green'
+            Write-UserMessage -Message "`tActual:`t`t$($actuals[$_])" -Color 'Red'
         }
     }
 
     if ($Update) {
         if ($current.manifest.url -and $current.manifest.hash) {
             $current.manifest.hash = $actuals
         } else {
-            $platforms = ($current.manifest.architecture | Get-Member -MemberType NoteProperty).Name
+            $platforms = ($current.manifest.architecture | Get-Member -MemberType 'NoteProperty').Name
             # Defaults to zero, don't know, which architecture is available
             $64bit_count = 0
             $32bit_count = 0
@@ -171,7 +167,7 @@ foreach ($current in $MANIFESTS) {
             }
         }
 
-        Write-UserMessage -Message "Writing updated $($current.app) manifest" -Color DarkGreen
+        Write-UserMessage -Message "Writing updated $($current.app) manifest" -Color 'DarkGreen'
 
         $p = Join-Path $Dir "$($current.app).json"
 

bin/checkurls.ps1

@@ -2,23 +2,23 @@
 .SYNOPSIS
     List manifests which do not have valid URLs.
 .PARAMETER App
-    Manifest name to search.
-    Wildcards is supported.
+    Specifies the manifest name to search.
+    Wildcards are supported.
 .PARAMETER Dir
-    Where to search for manifest(s).
+    Specifies the location of manifests.
 .PARAMETER Timeout
-    How long (seconds) the request can be pending before it times out.
+    Specifies how long (seconds) the request can be pending before it times out.
 .PARAMETER SkipValid
-    Manifests will all valid URLs will not be shown.
+    Specifies to not show manifests, which have all URLs valid.
 #>
 param(
     [SupportsWildcards()]
     [String] $App = '*',
-    [Parameter(Mandatory = $true)]
+    [Parameter(Mandatory)]
     [ValidateScript( {
-        if (!(Test-Path $_ -Type Container)) { throw "$_ is not a directory!" }
-        $true
-    })]
+            if (!(Test-Path $_ -Type 'Container')) { throw "$_ is not a directory!" }
+            $true
+        })]
     [String] $Dir,
     [Int] $Timeout = 5,
     [Switch] $SkipValid
@@ -39,13 +39,13 @@ Get-ChildItem $Dir "$App.*" -File | ForEach-Object {
 }
 
 Write-Host '[' -NoNewline
-Write-Host 'U' -NoNewline -ForegroundColor Cyan
+Write-Host 'U' -ForegroundColor 'Cyan' -NoNewline
 Write-Host ']RLs'
 Write-Host ' | [' -NoNewline
-Write-Host 'O' -NoNewline -ForegroundColor Green
+Write-Host 'O' -ForegroundColor 'Green' -NoNewline
 Write-Host ']kay'
 Write-Host ' |  | [' -NoNewline
-Write-Host 'F' -NoNewline -ForegroundColor Red
+Write-Host 'F' -ForegroundColor 'Red' -NoNewline
 Write-Host ']ailed'
 Write-Host ' |  |  |'
 
@@ -103,7 +103,7 @@ foreach ($man in $Queue) {
 
     # URLS
     Write-Host '[' -NoNewline
-    Write-Host $urls.Length -NoNewline -ForegroundColor Cyan
+    Write-Host $urls.Length -ForegroundColor 'Cyan' -NoNewline
     Write-Host ']' -NoNewline
 
     # Okay
@@ -125,6 +125,6 @@ foreach ($man in $Queue) {
     Write-Host (strip_ext $name)
 
     $errors | ForEach-Object {
-        Write-Host "       > $_" -ForegroundColor DarkRed
+        Write-Host "       > $_" -ForegroundColor 'DarkRed'
     }
 }