Merge pull request #7383 from AndrolGenhald/test-documentation-issues…

…-index

bin/generate_issues_list_doc.php

@@ -0,0 +1,25 @@
+#!/usr/bin/env php
+<?php
+
+$docs_dir = dirname(__DIR__) . DIRECTORY_SEPARATOR . "docs"
+    . DIRECTORY_SEPARATOR . "running_psalm" . DIRECTORY_SEPARATOR;
+$issues_index = "{$docs_dir}issues.md";
+$issues_dir = "{$docs_dir}issues";
+
+if (!file_exists($issues_dir)) {
+    throw new UnexpectedValueException("Issues documentation not found");
+}
+
+$issues_list = array_filter(array_map(function (string $issue_file) {
+    if ($issue_file === "." || $issue_file === ".." || substr($issue_file, -3) !== ".md") {
+        return false;
+    }
+
+    $issue = substr($issue_file, 0, strlen($issue_file) - 3);
+    return " - [$issue](issues/$issue.md)";
+}, scandir($issues_dir)));
+
+usort($issues_list, "strcasecmp");
+
+$issues_md_contents = array_merge(["# Issue types", ""], $issues_list, [""]);
+file_put_contents($issues_index, implode("\n", $issues_md_contents));

docs/running_psalm/issues.md

@@ -7,6 +7,7 @@
  - [CircularReference](issues/CircularReference.md)
  - [ComplexFunction](issues/ComplexFunction.md)
  - [ComplexMethod](issues/ComplexMethod.md)
+ - [ConfigIssue](issues/ConfigIssue.md)
  - [ConflictingReferenceConstraint](issues/ConflictingReferenceConstraint.md)
  - [ConstructorSignatureMismatch](issues/ConstructorSignatureMismatch.md)
  - [ContinueOutsideLoop](issues/ContinueOutsideLoop.md)
@@ -21,6 +22,8 @@
  - [DuplicateArrayKey](issues/DuplicateArrayKey.md)
  - [DuplicateClass](issues/DuplicateClass.md)
  - [DuplicateConstant](issues/DuplicateConstant.md)
+ - [DuplicateEnumCase](issues/DuplicateEnumCase.md)
+ - [DuplicateEnumCaseValue](issues/DuplicateEnumCaseValue.md)
  - [DuplicateFunction](issues/DuplicateFunction.md)
  - [DuplicateMethod](issues/DuplicateMethod.md)
  - [DuplicateParam](issues/DuplicateParam.md)
@@ -62,6 +65,7 @@
  - [InvalidDocblock](issues/InvalidDocblock.md)
  - [InvalidDocblockParamName](issues/InvalidDocblockParamName.md)
  - [InvalidEnumBackingType](issues/InvalidEnumBackingType.md)
+ - [InvalidEnumCaseValue](issues/InvalidEnumCaseValue.md)
  - [InvalidExtendClass](issues/InvalidExtendClass.md)
  - [InvalidFalsableReturnType](issues/InvalidFalsableReturnType.md)
  - [InvalidFunctionCall](issues/InvalidFunctionCall.md)
@@ -132,6 +136,7 @@
  - [MoreSpecificReturnType](issues/MoreSpecificReturnType.md)
  - [MutableDependency](issues/MutableDependency.md)
  - [NamedArgumentNotAllowed](issues/NamedArgumentNotAllowed.md)
+ - [NoEnumProperties](issues/NoEnumProperties.md)
  - [NoInterfaceProperties](issues/NoInterfaceProperties.md)
  - [NonInvariantDocblockPropertyType](issues/NonInvariantDocblockPropertyType.md)
  - [NonInvariantPropertyType](issues/NonInvariantPropertyType.md)
@@ -166,6 +171,7 @@
  - [PossiblyInvalidArrayOffset](issues/PossiblyInvalidArrayOffset.md)
  - [PossiblyInvalidCast](issues/PossiblyInvalidCast.md)
  - [PossiblyInvalidClone](issues/PossiblyInvalidClone.md)
+ - [PossiblyInvalidDocblockTag](issues/PossiblyInvalidDocblockTag.md)
  - [PossiblyInvalidFunctionCall](issues/PossiblyInvalidFunctionCall.md)
  - [PossiblyInvalidIterator](issues/PossiblyInvalidIterator.md)
  - [PossiblyInvalidMethodCall](issues/PossiblyInvalidMethodCall.md)
@@ -193,6 +199,7 @@
  - [PossiblyUnusedMethod](issues/PossiblyUnusedMethod.md)
  - [PossiblyUnusedParam](issues/PossiblyUnusedParam.md)
  - [PossiblyUnusedProperty](issues/PossiblyUnusedProperty.md)
+ - [PossiblyUnusedReturnValue](issues/PossiblyUnusedReturnValue.md)
  - [PropertyNotSetInConstructor](issues/PropertyNotSetInConstructor.md)
  - [PropertyTypeCoercion](issues/PropertyTypeCoercion.md)
  - [RawObjectIteration](issues/RawObjectIteration.md)
@@ -221,6 +228,7 @@
  - [TaintedSql](issues/TaintedSql.md)
  - [TaintedSSRF](issues/TaintedSSRF.md)
  - [TaintedSystemSecret](issues/TaintedSystemSecret.md)
+ - [TaintedTextWithQuotes](issues/TaintedTextWithQuotes.md)
  - [TaintedUnserialize](issues/TaintedUnserialize.md)
  - [TaintedUserSecret](issues/TaintedUserSecret.md)
  - [TooFewArguments](issues/TooFewArguments.md)
@@ -259,14 +267,17 @@
  - [UnrecognizedExpression](issues/UnrecognizedExpression.md)
  - [UnrecognizedStatement](issues/UnrecognizedStatement.md)
  - [UnresolvableInclude](issues/UnresolvableInclude.md)
+ - [UnsafeGenericInstantiation](issues/UnsafeGenericInstantiation.md)
  - [UnsafeInstantiation](issues/UnsafeInstantiation.md)
  - [UnusedClass](issues/UnusedClass.md)
  - [UnusedClosureParam](issues/UnusedClosureParam.md)
  - [UnusedConstructor](issues/UnusedConstructor.md)
+ - [UnusedForeachValue](issues/UnusedForeachValue.md)
  - [UnusedFunctionCall](issues/UnusedFunctionCall.md)
  - [UnusedMethod](issues/UnusedMethod.md)
  - [UnusedMethodCall](issues/UnusedMethodCall.md)
  - [UnusedParam](issues/UnusedParam.md)
  - [UnusedProperty](issues/UnusedProperty.md)
  - [UnusedPsalmSuppress](issues/UnusedPsalmSuppress.md)
+ - [UnusedReturnValue](issues/UnusedReturnValue.md)
  - [UnusedVariable](issues/UnusedVariable.md)

docs/running_psalm/issues/ComplexFunction.md

@@ -0,0 +1,3 @@
+# ComplexFunction
+
+Emitted when a function is too complicated. Complicated functions should be split up.

docs/running_psalm/issues/ComplexMethod.md

@@ -0,0 +1,3 @@
+# ComplexMethod
+
+Emitted when a method is too complicated. Complicated methods should be split up.

tests/DocumentationTest.php

@@ -18,26 +18,35 @@
 use Psalm\Tests\Internal\Provider\FakeParserCacheProvider;
 use UnexpectedValueException;
 
+use function array_diff;
 use function array_filter;
 use function array_keys;
+use function array_map;
 use function array_shift;
 use function count;
 use function dirname;
 use function explode;
+use function file;
 use function file_exists;
 use function file_get_contents;
 use function glob;
 use function implode;
 use function in_array;
+use function preg_match;
 use function preg_quote;
+use function scandir;
 use function sort;
 use function str_replace;
+use function strlen;
 use function strpos;
 use function substr;
 use function trim;
+use function usort;
 use function var_export;
 
 use const DIRECTORY_SEPARATOR;
+use const FILE_IGNORE_NEW_LINES;
+use const FILE_SKIP_EMPTY_LINES;
 use const LIBXML_NONET;
 
 class DocumentationTest extends TestCase
@@ -90,7 +99,7 @@ class DocumentationTest extends TestCase
      */
     private static function getCodeBlocksFromDocs(): array
     {
-        $issues_dir = dirname(dirname(__FILE__)) . DIRECTORY_SEPARATOR . 'docs' . DIRECTORY_SEPARATOR . 'running_psalm' . DIRECTORY_SEPARATOR . 'issues';
+        $issues_dir = dirname(__DIR__) . DIRECTORY_SEPARATOR . 'docs' . DIRECTORY_SEPARATOR . 'running_psalm' . DIRECTORY_SEPARATOR . 'issues';
 
         if (!file_exists($issues_dir)) {
             throw new UnexpectedValueException('docs not found');
@@ -422,4 +431,52 @@ protected function failureDescription($other): string
             }
         };
     }
+
+    /**
+     * Tests that issues.md contains the expected links to issue documentation.
+     * issues.md can be generated automatically with bin/generate_documentation_issues_list.php.
+     */
+    public function testIssuesIndex(): void
+    {
+        $docs_dir = dirname(__DIR__) . DIRECTORY_SEPARATOR . "docs" . DIRECTORY_SEPARATOR . "running_psalm" . DIRECTORY_SEPARATOR;
+        $issues_index = "{$docs_dir}issues.md";
+        $issues_dir = "{$docs_dir}issues";
+
+        if (!file_exists($issues_dir)) {
+            throw new UnexpectedValueException("Issues documentation not found");
+        }
+
+        if (!file_exists($issues_index)) {
+            throw new UnexpectedValueException("Issues index not found");
+        }
+
+        $issues_index_contents = file($issues_index, FILE_IGNORE_NEW_LINES|FILE_SKIP_EMPTY_LINES);
+        array_shift($issues_index_contents); // Remove title
+
+        $issues_index_list = array_map(function (string $issues_line) {
+            preg_match('/^ - \[([^\]]*)\]\(issues\/\1\.md\)$/', $issues_line, $matches);
+            $this->assertCount(2, $matches, "Invalid format in issues index: $issues_line");
+            return $matches[1];
+        }, $issues_index_contents);
+
+        $issue_files = array_filter(array_map(function (string $issue_file) {
+            if ($issue_file === "." || $issue_file === "..") {
+                return false;
+            }
+            $this->assertStringEndsWith(".md", $issue_file, "Invalid file in issues documentation: $issue_file");
+            return substr($issue_file, 0, strlen($issue_file) - 3);
+        }, scandir($issues_dir)));
+
+        $unlisted_issues = array_diff($issue_files, $issues_index_list);
+        $this->assertEmpty($unlisted_issues, "Issue documentation missing from issues.md: " . implode(", ", $unlisted_issues));
+
+        $missing_documentation = array_diff($issues_index_list, $issue_files);
+        $this->assertEmpty($missing_documentation, "issues.md has link to non-existent documentation for: " . implode(", ", $missing_documentation));
+
+        $sorted = $issues_index_list;
+        usort($sorted, "strcasecmp");
+        for ($i = 0; $i < count($sorted); ++$i) {
+            $this->assertEquals($sorted[$i], $issues_index_list[$i], "issues.md out of order, expected {$sorted[$i]} before {$issues_index_list[$i]}");
+        }
+    }
 }