Merge remote-tracking branch 'upstream/main'

Author: dantleech

SECURITY.md

@@ -0,0 +1,41 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V0.0.8 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
+
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report).
+
+If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey).
+
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs.
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

composer.json

@@ -18,5 +18,8 @@
     ],
     "autoload": {
         "psr-4": { "Microsoft\\PhpParser\\": ["src/"] }
+    },
+    "autoload-dev": {
+        "psr-4": { "Microsoft\\PhpParser\\Tests\\Unit\\": ["tests/unit/"] }
     }
 }

docs/HowItWorks.md

@@ -306,7 +306,7 @@ Note that for this error case, it is more of an art than a science. That is to s
 would add special casing for anticipated scenarios, rather than construct some general-purpose rule.
 
 #### Other notes
-* Just as it's imporant to understand the assumptions that *will* hold true,
+* Just as it's important to understand the assumptions that *will* hold true,
 it is also important to understand the assumptions that will not hold true.
 One such **non-invariant** is that not every token generated by the lexer ends up in the tree.
 
@@ -387,6 +387,6 @@ existing, more battle-tested, work to validate our own correctness.
 degree of variance, we should set up some infrastructure to help us ensure that performance work results in a statistically
 significant boost and works on a wide variety of machine configurations.
 * Fuzz testing - test the parser against automatically generated inputs to exercise edge cases in a bulk fashion, and
-and ensure expected properties of the tree.
+ensure expected properties of the tree.
 * Community feedback - try and get the parser in the hands of as many people as possible so we can validate a
 wide range of use cases. The Syntax Visualizer tool is one tool to help us increase reach.

docs/Overview.md

@@ -75,5 +75,5 @@ all incorrect constructs (e.g. including a non-constant expression as the defaul
 a method parameter). Instead, it attaches these errors on a post-parse walk of the tree.
 
 ## Next Steps
-Check out the [Readme](../README.md) and [Getting Started](GettingStarted.md) pages for more information on how consume
-the parser, or the [How It Works](HowItWorks.md) section if you want to dive deeper into the implementation.
+Check out the [Readme](../README.md) and [Getting Started](GettingStarted.md) pages for more information on how to 
+consume the parser, or the [How It Works](HowItWorks.md) section if you want to dive deeper into the implementation.

phpstan.neon

@@ -1,5 +1,5 @@
 parameters:
-    level: 3
+    level: 4
     paths:
         - src/
     ignoreErrors:

src/DiagnosticsProvider.php

@@ -51,6 +51,8 @@ public static function checkDiagnostics($node) {
         if ($node instanceof Node) {
             return $node->getDiagnosticForNode();
         }
+
+        /** @phpstan-ignore-next-line because it says "unreachable" statement */
         return null;
     }
 

src/Node.php

@@ -437,10 +437,7 @@ public function getLastChild() {
     public function getDescendantNodeAtPosition(int $pos) {
         foreach ($this->getChildNodes() as $child) {
             if ($child->containsPosition($pos)) {
-                $node = $child->getDescendantNodeAtPosition($pos);
-                if (!is_null($node)) {
-                    return $node;
-                }
+                return $child->getDescendantNodeAtPosition($pos);
             }
         }
 
@@ -590,6 +587,7 @@ public function getNamespaceDefinition() {
             ? $this
             : $this->getFirstAncestor(NamespaceDefinition::class, SourceFileNode::class);
 
+        /** @phpstan-ignore-next-line result is always false -- not sure this can happen */
         if ($namespaceDefinition instanceof NamespaceDefinition && !($namespaceDefinition->parent instanceof SourceFileNode)) {
             $namespaceDefinition = $namespaceDefinition->getFirstAncestor(SourceFileNode::class);
         }

src/Node/Expression/ArgumentExpression.php

@@ -6,6 +6,7 @@
 
 namespace Microsoft\PhpParser\Node\Expression;
 
+use Microsoft\PhpParser\MissingToken;
 use Microsoft\PhpParser\Node\Expression;
 use Microsoft\PhpParser\Token;
 
@@ -19,7 +20,7 @@ class ArgumentExpression extends Expression {
     /** @var Token|null */
     public $dotDotDotToken;
 
-    /** @var Expression|null null for first-class callable syntax */
+    /** @var Expression|MissingToken|null for first-class callable syntax */
     public $expression;
 
     const CHILD_NAMES = [

src/Node/InterfaceBaseClause.php

@@ -10,7 +10,7 @@
 use Microsoft\PhpParser\Token;
 
 class InterfaceBaseClause extends Node {
-    /** @var Token */
+    /** @var Token|null */
     public $extendsKeyword;
 
     /** @var DelimitedList\QualifiedNameList */

src/Node/NamespaceUseGroupClause.php

@@ -11,7 +11,7 @@
 
 class NamespaceUseGroupClause extends Node {
 
-    /** @var Token */
+    /** @var Token|null */
     public $functionOrConst;
     /** @var QualifiedName */
     public $namespaceName;