Add allowUndefinedVariablesInFileScope option (#193)

* Add test for allowUndefinedVariablesInFileScope

* Add descriptions for ScopeInfo properties

* Add allowUndefinedVariablesInFileScope to sniff

* Add allowUndefinedVariablesInFileScope to README

Author: sirbrillig

README.md

@@ -67,6 +67,7 @@ The available options are as follows:
 - `allowUnusedFunctionParameters` (bool, default `false`): if set to true, function arguments will never be marked as unused.
 - `allowUnusedCaughtExceptions` (bool, default `true`): if set to true, caught Exception variables will never be marked as unused.
 - `allowUnusedParametersBeforeUsed` (bool, default `true`): if set to true, unused function arguments will be ignored if they are followed by used function arguments.
+- `allowUndefinedVariablesInFileScope` (bool, default `false`): if set to true, undefined variables in the file's top-level scope will never be marked as undefined.
 - `validUnusedVariableNames` (string, default `null`): a space-separated list of names of placeholder variables that you want to ignore from unused variable warnings. For example, to ignore the variables `$junk` and `$unused`, this could be set to `'junk unused'`.
 - `ignoreUnusedRegexp` (string, default `null`): a PHP regexp string (note that this requires explicit delimiters) for variables that you want to ignore from unused variable warnings. For example, to ignore the variables `$_junk` and `$_unused`, this could be set to `'/^_/'`.
 - `validUndefinedVariableNames` (string, default `null`): a space-separated list of names of placeholder variables that you want to ignore from undefined variable warnings. For example, to ignore the variables `$post` and `$undefined`, this could be set to `'post undefined'`. This can be used in combination with `validUndefinedVariableRegexp`.

Tests/VariableAnalysisSniff/GlobalScopeTest.php

@@ -7,11 +7,34 @@ class GlobalScopeTest extends BaseTestCase {
   public function testGlobalScopeWarnings() {
     $fixtureFile = $this->getFixture('GlobalScopeFixture.php');
     $phpcsFile = $this->prepareLocalFileForSniffs($fixtureFile);
+    $phpcsFile->ruleset->setSniffProperty(
+      'VariableAnalysis\Sniffs\CodeAnalysis\VariableAnalysisSniff',
+      'allowUndefinedVariablesInFileScope',
+      'false'
+    );
     $phpcsFile->process();
     $lines = $this->getWarningLineNumbersFromFile($phpcsFile);
     $expectedErrors = [
       4,
       7,
+      10,
+    ];
+    $this->assertEquals($expectedErrors, $lines);
+  }
+
+  public function testGlobalScopeWarningsWithAllowUndefinedVariablesInFileScope() {
+    $fixtureFile = $this->getFixture('GlobalScopeFixture.php');
+    $phpcsFile = $this->prepareLocalFileForSniffs($fixtureFile);
+    $phpcsFile->ruleset->setSniffProperty(
+      'VariableAnalysis\Sniffs\CodeAnalysis\VariableAnalysisSniff',
+      'allowUndefinedVariablesInFileScope',
+      'true'
+    );
+    $phpcsFile->process();
+    $lines = $this->getWarningLineNumbersFromFile($phpcsFile);
+    $expectedErrors = [
+      4,
+      10,
     ];
     $this->assertEquals($expectedErrors, $lines);
   }

Tests/VariableAnalysisSniff/fixtures/GlobalScopeFixture.php

@@ -5,3 +5,7 @@
 
 echo $name;
 echo $activity; // undefined variable $activity
+
+function thisIsAFunction() {
+    echo $whatever; // undefined variable $whatever
+}

VariableAnalysis/Lib/ScopeInfo.php

@@ -7,11 +7,15 @@
  */
 class ScopeInfo {
   /**
+   * The token index of the start of this scope.
+   *
    * @var int
    */
   public $owner;
 
   /**
+   * The variables defined in this scope.
+   *
    * @var VariableInfo[]
    */
   public $variables = [];

VariableAnalysis/Sniffs/CodeAnalysis/VariableAnalysisSniff.php

@@ -66,12 +66,19 @@ class VariableAnalysisSniff implements Sniff {
 
   /**
    *  Allow function parameters to be unused without provoking unused-var warning.
-   *  Set generic.codeanalysis.variableanalysis.allowUnusedFunctionParameters to a true value.
    *
    *  @var bool
    */
   public $allowUnusedFunctionParameters = false;
 
+  /**
+   *  If set, ignores undefined variables in the file scope (the top-level
+   *  scope of a file).
+   *
+   *  @var bool
+   */
+  public $allowUndefinedVariablesInFileScope = false;
+
   /**
    *  A space-separated list of names of placeholder variables that you want to
    *  ignore from unused variable warnings. For example, to ignore the variables
@@ -316,6 +323,9 @@ protected function getOrCreateVariableInfo($varName, $currScope) {
       if (isset($this->ignoreUnusedRegexp) && preg_match($this->ignoreUnusedRegexp, $varName) === 1) {
         $scopeInfo->variables[$varName]->ignoreUnused = true;
       }
+      if ($scopeInfo->owner === 0 && $this->allowUndefinedVariablesInFileScope) {
+        $scopeInfo->variables[$varName]->ignoreUndefined = true;
+      }
       if (in_array($varName, $validUndefinedVariableNames)) {
         $scopeInfo->variables[$varName]->ignoreUndefined = true;
       }