@psalm-trace is now a specific low-level issue, because plain debug print breaks structured output (after #3080) (#3106)

config.xsd

@@ -337,6 +337,7 @@
             <xs:element name="ReservedWord" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="StringIncrement" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="TaintedInput" type="IssueHandlerType" minOccurs="0" />
+            <xs:element name="Trace" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="TraitMethodSignatureMismatch" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="TooFewArguments" type="ArgumentIssueHandlerType" minOccurs="0" />
             <xs:element name="TooManyArguments" type="ArgumentIssueHandlerType" minOccurs="0" />
@@ -359,6 +360,7 @@
             <xs:element name="UndefinedPropertyFetch" type="PropertyIssueHandlerType" minOccurs="0" />
             <xs:element name="UndefinedThisPropertyAssignment" type="PropertyIssueHandlerType" minOccurs="0" />
             <xs:element name="UndefinedThisPropertyFetch" type="PropertyIssueHandlerType" minOccurs="0" />
+            <xs:element name="UndefinedTrace" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UndefinedTrait" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UndefinedGlobalVariable" type="IssueHandlerType" minOccurs="0" />
             <xs:element name="UndefinedVariable" type="IssueHandlerType" minOccurs="0" />

docs/annotating_code/supported_annotations.md

@@ -397,6 +397,8 @@ $username = $_GET['username']; // prints something like "test.php:4 $username: m
 
 ```
 
+*Note*: it throws [special low-level issue](../running_psalm/issues/Trace.md), so you have to set errorLevel to 1, override it in config or invoke Psalm with `--show-info=true`.
+
 ## Type Syntax
 
 Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/guides/types.html), and also the [proposed PHPDoc PSR type syntax](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types).

docs/running_psalm/error_levels.md

@@ -98,6 +98,8 @@ Level 5 and above allows a more non-verifiable code, and higher levels are even
  - [MixedStringOffsetAssignment](issues/MixedStringOffsetAssignment.md)
  - [MutableDependency](issues/MutableDependency.md)
  - [PossiblyNullOperand](issues/PossiblyNullOperand.md)
+ - [Trace](issues/Trace.md)
+ - [UndefinedTrace](issues/UndefinedTrace.md)
 
 ## Errors ignored at level 3 and higher
 

docs/running_psalm/issues/Trace.md

@@ -0,0 +1,14 @@
+# Trace
+
+Not really an issue. Just reports type of the variable.
+
+```php
+<?php
+
+/** @psalm-trace $x */
+$x = getmypid();
+```
+
+## How to fix
+
+Use it for debugging purposes, not for production

docs/running_psalm/issues/UndefinedTrace.md

@@ -0,0 +1,14 @@
+# UndefinedTrace
+
+Attempt to trace an undefined variable
+
+```php
+<?php
+
+/** @psalm-trace $x */
+echo 'Hello World!';
+```
+
+## How to fix
+
+Provide existing variable or remove it

src/Psalm/Internal/Analyzer/StatementsAnalyzer.php

@@ -32,6 +32,8 @@ use Psalm\Issue\ForbiddenEcho;
 use Psalm\Issue\ImpureFunctionCall;
 use Psalm\Issue\InvalidDocblock;
 use Psalm\Issue\InvalidGlobal;
+use Psalm\Issue\Trace;
+use Psalm\Issue\UndefinedTrace;
 use Psalm\Issue\UnevaluatedCode;
 use Psalm\Issue\UnrecognizedStatement;
 use Psalm\Issue\UnusedVariable;
@@ -935,8 +937,25 @@ class StatementsAnalyzer extends SourceAnalyzer implements StatementsSource
 
             foreach ($traced_variables as $traced_variable) {
                 if (isset($context->vars_in_scope[$traced_variable])) {
-                    echo $this->getFileName() . ':' . $stmt->getLine() . ' ' . $traced_variable . ': '
-                        . $context->vars_in_scope[$traced_variable]->getId() . "\n";
+                    if (IssueBuffer::accepts(
+                        new Trace(
+                            $traced_variable . ': ' . $context->vars_in_scope[$traced_variable]->getId(),
+                            new CodeLocation($this->source, $stmt)
+                        ),
+                        $this->getSuppressedIssues()
+                    )) {
+                        // fall through
+                    }
+                } else {
+                    if (IssueBuffer::accepts(
+                        new UndefinedTrace(
+                            'Attempt to trace undefined variable ' . $traced_variable,
+                            new CodeLocation($this->source, $stmt)
+                        ),
+                        $this->getSuppressedIssues()
+                    )) {
+                        // fall through
+                    }
                 }
             }
         }

src/Psalm/Issue/Trace.php

@@ -0,0 +1,10 @@
+<?php
+
+
+namespace Psalm\Issue;
+
+class Trace extends CodeIssue
+{
+    const ERROR_LEVEL = 1;
+    const SHORTCODE = 224;
+}

src/Psalm/Issue/UndefinedTrace.php

@@ -0,0 +1,10 @@
+<?php
+
+
+namespace Psalm\Issue;
+
+class UndefinedTrace extends CodeIssue
+{
+    const ERROR_LEVEL = 2;
+    const SHORTCODE = 225;
+}

tests/TraceTest.php

@@ -0,0 +1,31 @@
+<?php
+namespace Psalm\Tests;
+
+class TraceTest extends TestCase
+{
+    use Traits\InvalidCodeAnalysisTestTrait;
+
+    /**
+     * @return iterable<string,array{string,error_message:string,2?:string[],3?:bool,4?:string}>
+     */
+    public function providerInvalidCodeParse()
+    {
+        return [
+            'traceVariable' => [
+                '<?php
+                    /** @psalm-trace $a */
+                    $a = getmypid();',
+                'error_message' => 'Trace',
+            ],
+            'undefinedTraceVariable' => [
+                '<?php
+                    /** @psalm-trace $b */
+                    echo 1;',
+                'error_message' => 'UndefinedTrace',
+                'error_levels' => [
+                    'MixedAssignment',
+                ],
+            ]
+        ];
+    }
+}