New Rule Suggestion: AvoidReuseOfAutomaticVariables

[Glober777]

I think it would be really helpful, if there was a rule that would point out when there's attempt to reuse (assign something to) an automatic variable, as sometimes, those may get reused by mistake, like $Host, $Home, $Args, $Input, etc. While in some cases the engine will throw out an error during the execution (i.e. $Host = 'Hello!'), there are occasions when no errors will show up, like $Args = 'Hello!'. The inability to retrieve the assigned value back from the $Args may be confusing to those people who don't yet know that $Args is actually an automatic variable.

[mklement0]

For convenience, here's the list of all automatic variables that shouldn't be writable, but currently are (copied from the linked issue):

As @lzybkr has pointed out, this lists needs careful vetting, however, to prevent false positives.

Name                          Predefined
----                          ----------
_                                  False
AllNodes                           False
Args                                True
Event                              False
EventArgs                          False
EventSubscriber                    False
ForEach                             True
Input                               True
Matches                             True
MyInvocation                        True
NestedPromptLevel                   True
Profile                             True
PSBoundParameters                   True
PsCmdlet                           False
PSCommandPath                       True
PSDebugContext                     False
PSItem                             False
PSScriptRoot                        True
PSSenderInfo                       False
Pwd                                 True
ReportErrorShowExceptionClass      False
ReportErrorShowInnerException      False
ReportErrorShowSource              False
ReportErrorShowStackTrace          False
Sender                             False
StackTrace                          True
This                               False

"Predefined" refers to whether they exist in the global scope by default.

Some of them are only defined in certain contexts, but, arguably, to prevent confusion, preventing their custom use categorically is the right approach.

The following code was used to detect them (note that it has to rely on parsing the help topic to identify all automatic variables - I'm not aware of a better way):

$autoVarNames = ((get-help about_automatic_variables) -split [environment]::newline -match '^\s*\$\w+\s*$').Trim().Trim('$') | Sort-Object -Unique

foreach ($varName in $autoVarNames) {
  $var = Get-Variable $varName -ErrorAction 'SilentlyContinue'
  $exists = $?
  if ($exists -and $var.Options -match 'readonly|constant') {
    Write-Verbose "$varName`: read-only or constant"
  } elseif ($varName -in 'NULL', 'OFS', 'LastExitCode') { # exceptions
    Write-Verbose "$varName`: writable by design"
  } else {
    Set-Variable -Name $varName -Value $null -ErrorAction SilentlyContinue
    if ($?) {
      [pscustomobject] @{ Name = $varName; Predefined = $exists }
    }
  }
}

Note that the code has a fixed list of exceptions so as not to report automatic variables that should indeed be writable, such as $OFS, and $LastExitCode, or assignable as a quiet no-op, such as $NULL - do tell us if other exceptions are missing.

[iSazonov]

We need two rule:

1. $_ /$PSItem and $input should be read only.
   Conclusion @powershell-committee for $_/$PSItem Should we detect/Deny using $_ as a user defined variable? PowerShell#3695 (comment)
   Conclusion @powershell-committee for $input Set-StrictMode should detect use of automatic variables as parameters or the target of an assignment PowerShell#3061 (comment)
2. For rest automatic variables "It is recommended to be read only (don't reuse)"
   Conclusion @powershell-committee for this. Set-StrictMode should detect use of automatic variables as parameters or the target of an assignment PowerShell#3061 (comment)

[mklement0]

Just coming across this again, @iSazonov: The committee ultimately decided not to enforce the read-only status of any automatic variables at the engine level - see PowerShell/PowerShell#3695 (comment).

[bergmeister]

@mklement0 I created the AvoidAssignmentToAutomaticVariable rule a year ago for it and made it lint on read-only variables only so far, more automatic variables could be added.

[mklement0]

^{Sorry, @bergmeister - it took a while for some conceptual fog to clear, so I've deleted the previous comment - hopefully, this one now presents a clear picture.}

Thanks, @bergmeister - didn't actually know about that rule. Since it doesn't cover the truly problematic cases listed above - those that aren't read-only, but should be, adding these variables is indeed needed.

I think two actions are needed:

• Activate PSAvoidAssignmentToAutomaticVariable by default in the VSCode PowerShell extension - it currently isn't, which is why I (and probably many others) was unaware of it.

• Add the variables listed above to the existing PSAvoidAssignmentToAutomaticVariable rule, as warnings.

  • They should only be warnings, because you can sometimes get away with setting such automatic variables - notably in the case of $_ / $PSItem - and there definitely is code out there that does it.

P.S.: I've just summarized the issue of inadvertently assigning to automatic variables in this Stack Overflow answer, which describes the status quo (this is partially a note to self to remind me of updating that answer once the actions above are implemented).

[bergmeister]

Yes, I forgot to add that rule to the default set of rules uses in the vs code extension, I created a PR for this: PowerShell/PowerShellEditorServices#1101

Yes, there is the backlog of warning also on non-readonly variables, I did not do it straight away because I got push-back from Jason because some of them can be assigned to by design and there was homework to do, which non-read-only variables we should warn about but it seems you've already done that, so all we have to do is add them here in a 2nd list of variables with lower severity. If you could give me just a list of variables to add to this new list, that would be great so that I don't have to go through the effort of reading and understanding your long post :-)