Unused function, extension and package detection

bin/stubs/gen_preloader.php

@@ -55,8 +55,10 @@
     RecursiveIteratorIterator::LEAVES_ONLY,
 ) as $f
 ) {
-    $f = str_replace(['/', '.php', 'src\\'], ['\\', '', ''], $f);
-    $classes[$f] = true;
+    if (str_ends_with($f, '.php')) {
+        $f = str_replace(['/', '.php', 'src\\'], ['\\', '', ''], $f);
+        $classes[$f] = true;
+    }
 }
 
 foreach ($classes as $class => $_) {

config.xsd

@@ -24,6 +24,8 @@
             <xs:element name="universalObjectCrates" type="UniversalObjectCratesType" minOccurs="0" maxOccurs="1" />
             <xs:element name="enableExtensions" type="ExtensionsType" minOccurs="0" maxOccurs="1" />
             <xs:element name="disableExtensions" type="ExtensionsType" minOccurs="0" maxOccurs="1" />
+            <xs:element name="ignoreUnusedExtensions" type="AnyExtensionsType" minOccurs="0" maxOccurs="1" />
+            <xs:element name="ignoreUnusedComposerPackages" type="PackagesType" minOccurs="0" maxOccurs="1" />
         </xs:choice>
 
         <xs:attribute name="autoloader" type="xs:string" />
@@ -114,6 +116,7 @@
     <xs:complexType name="StubsAttributeType">
         <xs:attribute name="name" type="xs:string" use="required" />
         <xs:attribute name="preloadClasses" type="xs:boolean" default="false" />
+        <xs:attribute name="extension" type="xs:string" default="" />
         <xs:anyAttribute processContents="skip" />
     </xs:complexType>
 
@@ -748,6 +751,18 @@
         </xs:sequence>
     </xs:complexType>
 
+    <xs:complexType name="AnyExtensionsType">
+        <xs:sequence>
+            <xs:element name="extension" maxOccurs="unbounded" type="PackageAttributeType" />
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="PackagesType">
+        <xs:sequence>
+            <xs:element name="package" maxOccurs="unbounded" type="PackageAttributeType" />
+        </xs:sequence>
+    </xs:complexType>
+
     <xs:simpleType name="ExtensionType">
         <xs:restriction base="xs:string">
             <xs:enumeration value="amqp"/>
@@ -774,4 +789,8 @@
     <xs:complexType name="ExtensionAttributeType">
         <xs:attribute name="name" type="ExtensionType" use="required" />
     </xs:complexType>
+
+    <xs:complexType name="PackageAttributeType">
+        <xs:attribute name="name" type="xs:string" use="required" />
+    </xs:complexType>
 </xs:schema>

docs/running_psalm/configuration.md

@@ -625,6 +625,31 @@ Optional. A list of extensions to disable. By default, only extensions required
 </disableExtensions>
 ```
 
+
+#### &lt;ignoreUnusedComposerPackages&gt;
+
+Optional. A list of packages for which [UnusedComposerPackage](issues/UnusedComposerPackage.md) issues should not be emitted, even if they're not used in the current project.  
+
+Useful for example for peer dependencies (dependencies which are only used by another dependency, aren't explicitly required by that dependency's composer.json, and aren't used in the current project).  
+
+```xml
+<ignoreUnusedComposerPackages>
+  <package name="symfony/polyfill-php84"/>
+</ignoreUnusedComposerPackages>
+```
+
+#### &lt;ignoreUnusedExtensions&gt;
+
+Optional. A list of extensions for which [UnusedExtension](issues/UnusedExtension.md) issues should not be emitted, even if they're not used in the current project.
+
+Useful for example for peer dependencies (extensions which are only used by another dependency, aren't explicitly required by that dependency's composer.json, and aren't used in the current project).  
+
+```xml
+<ignoreUnusedExtensions>
+  <extension name="bcmath"/>
+</ignoreUnusedExtensions>
+```
+
 #### &lt;plugins&gt;
 Optional. A list of `<plugin filename="path_to_plugin.php" />` entries. See the [Plugins](plugins/using_plugins.md) section for more information.
 
@@ -645,12 +670,16 @@ functions without the implementations.
 
 You can find a list of stubs for common classes [here](https://github.com/JetBrains/phpstorm-stubs).
 List out each file with `<file name="path/to/file.php" />`. In case classes to be tested use parent classes
-or interfaces defined in a stub file, this stub should be configured with attribute `preloadClasses="true"`.
+or interfaces defined in a stub file, this stub should be configured with attribute `preloadClasses="true"`.  
+
+Extension stubs must also specify the name of the extension (used for dead code detection).  
 
 ```xml
 <stubs>
   <file name="path/to/file.php" />
   <file name="path/to/abstract-class.php" preloadClasses="true" />
+  <file name="path/to/extensionStub.php" extension="extension-name" />
+  <file name="path/to/extensionStub2.php" preloadClasses="true" extension="extension-name" />
 </stubs>
 ```
 

docs/running_psalm/error_levels.md

@@ -357,9 +357,12 @@ These issues are treated as errors at level 7 and below.
  - [UnnecessaryVarAnnotation](issues/UnnecessaryVarAnnotation.md)
  - [UnusedClass](issues/UnusedClass.md)
  - [UnusedClosureParam](issues/UnusedClosureParam.md)
+ - [UnusedComposerPackage](issues/UnusedComposerPackage.md)
  - [UnusedConstructor](issues/UnusedConstructor.md)
  - [UnusedDocblockParam](issues/UnusedDocblockParam.md)
+ - [UnusedExtension](issues/UnusedExtension.md)
  - [UnusedForeachValue](issues/UnusedForeachValue.md)
+ - [UnusedFunction](issues/UnusedFunction.md)
  - [UnusedMethod](issues/UnusedMethod.md)
  - [UnusedParam](issues/UnusedParam.md)
  - [UnusedProperty](issues/UnusedProperty.md)

docs/running_psalm/issues.md

@@ -301,8 +301,10 @@
  - [UnusedBaselineEntry](issues/UnusedBaselineEntry.md)
  - [UnusedClass](issues/UnusedClass.md)
  - [UnusedClosureParam](issues/UnusedClosureParam.md)
+ - [UnusedComposerPackage](issues/UnusedComposerPackage.md)
  - [UnusedConstructor](issues/UnusedConstructor.md)
  - [UnusedDocblockParam](issues/UnusedDocblockParam.md)
+ - [UnusedExtension](issues/UnusedExtension.md)
  - [UnusedForeachValue](issues/UnusedForeachValue.md)
  - [UnusedFunctionCall](issues/UnusedFunctionCall.md)
  - [UnusedIssueHandlerSuppression](issues/UnusedIssueHandlerSuppression.md)

docs/running_psalm/issues/UnusedComposerPackage.md

@@ -0,0 +1,7 @@
+# UnusedComposerPackage
+
+Emitted when `composer.json` contains a package that is not referenced in the analyzed project.  
+
+To fix, remove the package from the `require` section of `composer.json`.  
+
+Peer dependencies (dependencies which are only used by another dependency, aren't explicitly required by that dependency's composer.json, and aren't used in the current project) may be excluded from unused composer package detection by using the [ignoreUnusedComposerPackages](https://psalm.dev/docs/running_psalm/configuration/#ignoreunusedcomposerpackages) config.

docs/running_psalm/issues/UnusedExtension.md

@@ -0,0 +1,7 @@
+# UnusedExtension
+
+Emitted when `composer.json` contains an extension that is not referenced in the analyzed project.  
+
+To fix, remove that extension from the `require` section of `composer.json`.  
+
+Peer dependencies (extensions which are only used by another dependency, aren't explicitly required by that dependency's composer.json, and aren't used in the current project) may be excluded from unused composer package detection by using the [ignoreUnusedExtensions](https://psalm.dev/docs/running_psalm/configuration/#ignoreunusedextensions) config.

docs/running_psalm/issues/UnusedFunction.md

@@ -0,0 +1,14 @@
+# UnusedFunction
+
+Emitted when `--find-dead-code` is turned on and Psalm cannot find any uses of a
+given function.
+
+If this class is used and part of the public API, annotate it with `@psalm-api`.
+
+```php
+<?php
+
+function a() {}
+function b() {}
+$a = a();
+```

src/Psalm/CodeLocation/ComposerJsonLocation.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Psalm\CodeLocation;
+
+use Psalm\CodeLocation;
+
+/** @psalm-immutable */
+final class ComposerJsonLocation extends CodeLocation
+{
+    public function __construct(
+        string $file_path,
+        int $file_start,
+        int $file_end,
+        int $line_number,
+    ) {
+        $this->file_start = $file_start;
+        // matches how CodeLocation works
+        $this->file_end = $file_end - 1;
+
+        $this->raw_file_start = $file_start;
+        $this->raw_file_end = $file_end;
+        $this->raw_line_number = $line_number;
+
+        $this->file_path = $file_path;
+        $this->file_name = 'composer.json';
+        $this->single_line = false;
+
+        $this->preview_start = $this->file_start;
+
+        $this->docblock_line_number = $line_number;
+    }
+}