build.ps1/build_helpers.ps1 issues

Read build.ps1 and tools/build-helpers.ps1, starting with ParseJasmine and RunSpecs, then review ExtractAtom and the build entry points against the linked lines. Done means the listed help, attribute, invocation, path, and parsing issues are addressed without breaking the build or Jasmine output.

Issue Description

build.ps1

• comment based help attempt to include an argument to the example statement, this causes PowerShell to invalidate the comment based help entirely.
  https://github.com/PowerShell/EditorSyntax/blob/cf27d6e54ff9fc593bfb46d22a671898fb31c0a9/build.ps1#L10
• [cmdletbinding()] and [parameter()] attributes are unnecessary.
  https://github.com/PowerShell/EditorSyntax/blob/cf27d6e54ff9fc593bfb46d22a671898fb31c0a9/build.ps1#L28-L33
• use of & (call operator) to execute commands with an unquoted (and non-expanded) name are unnecessary. (3 occurrences total)
  https://github.com/PowerShell/EditorSyntax/blob/cf27d6e54ff9fc593bfb46d22a671898fb31c0a9/build.ps1#L41

tools\build_helpers.ps1

function ExtractAtom

• doesn't support UNC paths due to $PSScriptRoot and Resolve-Path will format with the filesystem:: provider, which notation is not acceptable to [System.IO.Compression.ZipFile]::ExtractToDirectory() method. This is informational only, due to the fact that UNC paths do not work for NPM anyway.

function ParseJasmine

https://github.com/PowerShell/EditorSyntax/blob/cf27d6e54ff9fc593bfb46d22a671898fb31c0a9/tools/build-helpers.ps1#L38-L56

• first line starts with using $string parameter, the rest use $_. Surprisingly it works, but only because in RunSpecs the call to ParseJasmine is part of a ForEach-Object which populates the $_ automatic variable.
• the ^\s+Expected replacement doesn't seem to be working correctly. Maybe Atom/Atom-Grammar-Test has changed? I think 'to equal' now is to be 'instead found'.
• this function should really be a filter as it might provide a better fit. Note, also demonstrating the 'switch' statement with -regex parameter:

  filter ParseJasmine {
      switch -regex ($_) {
          ^\s+at {
              ''
              break
          }
  
          ^\s+it {
              $_ -replace '^(\s+)(it)', '$1[-] It'
              break
          }
  
          ^\s+Expected {
              $_ -replace '^(\s*)(Expected.*?)\s(instead found .*)', "`$1`$2`n`$1`$3"
              break
          }
  
          default {
              $_
          }
      }
  }
  

  This requires changing RunSpecs:
  https://github.com/PowerShell/EditorSyntax/blob/cf27d6e54ff9fc593bfb46d22a671898fb31c0a9/tools/build-helpers.ps1#L73
  to read more like:

          & $script:ATOM_EXE_PATH --test $specpath *>&1 | ParseJasmine
  

function RunSpecs

• quotes around the variable $script:ATOM_EXE_PATH are unneeded, probably old habit from CMD or another shell? (seen below)
• test path 'specs' is literal on ATOM command, but yet in a variable $specpath in a test previously. Only issue with using the variable is a chance to get the PowerShell filesystem:: provider notation injected.
  https://github.com/PowerShell/EditorSyntax/blob/cf27d6e54ff9fc593bfb46d22a671898fb31c0a9/tools/build-helpers.ps1#L72-L73

I'll post a PR shortly demonstrating these changes.