Merge pull request #11278 from vimeo/improve_stub_docs

Reorganize tools

.circleci/config.yml

@@ -44,7 +44,7 @@ jobs:
           at: /home/docker/project/
       - run:
           name: Build Phar file
-          command: bin/build-phar.sh
+          command: bin/ci/build-phar.sh
       - run:
           name: Smoke test Phar file
           # Change the root away from the project root to avoid conflicts with the Composer autoloader
@@ -71,13 +71,13 @@ jobs:
           at: /home/docker/project/
       - run:
           name: Analyse PHPUnit
-          command: bin/test-with-real-projects.sh phpunit
+          command: bin/ci/test-with-real-projects.sh phpunit
       - run:
           name: Analyse Psl
-          command: bin/test-with-real-projects.sh psl
+          command: bin/ci/test-with-real-projects.sh psl
       - run:
           name: Analyse Collections
-          command: bin/test-with-real-projects.sh collections
+          command: bin/ci/test-with-real-projects.sh collections
 
 # Orchestrate or schedule a set of jobs, see https://circleci.com/docs/2.0/workflows/
 workflows:

.github/workflows/build-phar.yml

@@ -74,7 +74,7 @@ jobs:
           # env:
           #   COMPOSER_ROOT_VERSION: dev-master
 
-      - run: bin/build-phar.sh
+      - run: bin/ci/build-phar.sh
         env:
           GPG_SIGNING: 1
           GPG_SECRET_KEY: ${{ secrets.GPG_SECRET_KEY }}
@@ -90,7 +90,7 @@ jobs:
           tag: ${{ github.ref }}
 
       - name: Release psalm/phar
-        run: bin/github-deploy-phar.sh
+        run: bin/ci/github-deploy-phar.sh
         env:
           PHAR_REPO_TOKEN: ${{ secrets.PHAR_REPO_TOKEN }}
 

.github/workflows/ci.yml

@@ -186,4 +186,4 @@ jobs:
           COMPOSER_ROOT_VERSION: dev-master
 
       - name: Run unit tests
-        run: bin/tests-github-actions.sh
+        run: bin/ci/tests-github-actions.sh

.github/workflows/windows-ci.yml

@@ -100,7 +100,7 @@ jobs:
           COMPOSER_ROOT_VERSION: dev-master
 
       - name: Generate test suits
-        run: php bin/generate_testsuites.php $env:CHUNK_COUNT
+        run: php bin/ci/generate_testsuites.php $env:CHUNK_COUNT
 
       - name: Run unit tests
         run: vendor/bin/paratest --processes=$env:PARALLEL_PROCESSES --testsuite=chunk_$env:CHUNK_NUMBER --log-junit build/phpunit/phpunit.xml

bin/test-with-real-projects.sh → bin/ci/test-with-real-projects.sh

@@ -5,8 +5,8 @@ set -x
 
 SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
 SCRIPT_DIR="$(realpath "$SCRIPT_DIR")"
-PSALM="$(readlink -f "$SCRIPT_DIR/../psalm")"
-PSALM_PHAR="$(readlink -f "$SCRIPT_DIR/../build/psalm.phar")"
+PSALM="$(readlink -f "$SCRIPT_DIR/../../psalm")"
+PSALM_PHAR="$(readlink -f "$SCRIPT_DIR/../../build/psalm.phar")"
 
 cd /tmp/
 rm -Rf testing-with-real-projects

bin/gen_callmap_utils.php → bin/stubs/gen_callmap_utils.php

@@ -2,6 +2,8 @@
 
 declare(strict_types=1);
 
+use PhpParser\Node\Stmt\Class_;
+use PhpParser\Node\Stmt\Namespace_;
 use Psalm\Internal\Analyzer\ProjectAnalyzer;
 use Psalm\Internal\Type\Comparator\UnionTypeComparator;
 use Psalm\Type;
@@ -228,3 +230,54 @@ function writeCallMap(string $file, array $callMap): void
 
 return '.var_export($callMap, true).';');
 }
+
+/**
+ * @template K as array-key
+ * @template V
+ * @param array<K, V> $a
+ * @param array<K, V> $b
+ * @return array<K, V>
+ */
+function get_changed_functions(array $a, array $b): array
+{
+    $changed_functions = [];
+
+    foreach (array_intersect_key($a, $b) as $function_name => $a_data) {
+        if (json_encode($b[$function_name]) !== json_encode($a_data)) {
+            $changed_functions[$function_name] = $b[$function_name];
+        }
+    }
+
+    return $changed_functions;
+}
+
+function extractClassesFromStatements(array $statements): array
+{
+    $classes = [];
+    foreach ($statements as $statement) {
+        if ($statement instanceof Class_) {
+            $classes[strtolower($statement->namespacedName->toString())] = true;
+        }
+        if ($statement instanceof Namespace_) {
+            $classes += extractClassesFromStatements($statement->stmts);
+        }
+    }
+
+    return $classes;
+}
+
+function serializeArray(array $array, string $prefix): string
+{
+    uksort($array, fn(string $first, string $second): int => strtolower($first) <=> strtolower($second));
+    $result = "[\n";
+    $localPrefix = $prefix . '    ';
+    foreach ($array as $key => $value) {
+        $result .= $localPrefix . var_export((string) $key, true) . ' => ' .
+            (is_array($value)
+            ? serializeArray($value, $localPrefix)
+            : var_export($value, true)) . ",\n";
+    }
+    $result .= $prefix . ']';
+
+    return $result;
+}

bin/update-property-map.php → bin/stubs/update-property-map.php

@@ -11,8 +11,6 @@
 //
 // What we are currently missing is properly parsing of <xi:include> directives.
 
-use PhpParser\Node\Stmt\Class_;
-use PhpParser\Node\Stmt\Namespace_;
 use PhpParser\NodeTraverser;
 use PhpParser\NodeVisitor\NameResolver;
 use PhpParser\ParserFactory;
@@ -21,32 +19,18 @@
     throw new ErrorException($str, 0, $num, $file, $line);
 });
 
-foreach ([__DIR__ . '/../../../autoload.php', __DIR__ . '/../vendor/autoload.php'] as $file) {
+foreach ([__DIR__ . '/../../../../autoload.php', __DIR__ . '/../../vendor/autoload.php'] as $file) {
     if (file_exists($file)) {
         require $file;
         break;
     }
 }
+require __DIR__ . '/gen_callmap_utils.php';
 
 $parser = (new ParserFactory)->createForNewestSupportedVersion();
 $traverser = new NodeTraverser();
 $traverser->addVisitor(new NameResolver);
 
-function extractClassesFromStatements(array $statements): array
-{
-    $classes = [];
-    foreach ($statements as $statement) {
-        if ($statement instanceof Class_) {
-            $classes[strtolower($statement->namespacedName->toString())] = true;
-        }
-        if ($statement instanceof Namespace_) {
-            $classes += extractClassesFromStatements($statement->stmts);
-        }
-    }
-
-    return $classes;
-}
-
 $stubbedClasses = [];
 foreach (new RecursiveDirectoryIterator(
     __DIR__ . '/../stubs',
@@ -161,22 +145,6 @@ function extractClassesFromStatements(array $statements): array
     }
 }
 
-function serializeArray(array $array, string $prefix): string
-{
-    uksort($array, fn(string $first, string $second): int => strtolower($first) <=> strtolower($second));
-    $result = "[\n";
-    $localPrefix = $prefix . '    ';
-    foreach ($array as $key => $value) {
-        $result .= $localPrefix . var_export((string) $key, true) . ' => ' .
-            (is_array($value)
-            ? serializeArray($value, $localPrefix)
-            : var_export($value, true)) . ",\n";
-    }
-    $result .= $prefix . ']';
-
-    return $result;
-}
-
 $serialized = serializeArray($classes, '');
 file_put_contents(
     dirname(__DIR__) . '/dictionaries/PropertyMap.php',

dictionaries/scripts/update_signaturemap_from_other_tool.php → bin/stubs/update_signaturemap_from_other_tool.php

@@ -1,5 +1,9 @@
 <?php
 
+declare(strict_types=1);
+
+require __DIR__ . '/gen_callmap_utils.php';
+
 $long_options = [
     'foreign-map-a:',
     'foreign-map-b:',
@@ -22,12 +26,12 @@
 // in the between local maps
 $useful_foreign_functions = array_diff_key(
     array_intersect_key(get_changed_functions($foreign_a, $foreign_b), $local_a),
-    get_changed_functions($local_a, $local_b)
+    get_changed_functions($local_a, $local_b),
 );
 
 $new_local = array_diff_key(
     array_merge($added_foreign_functions, $local_b, $useful_foreign_functions),
-    $removed_foreign_functions
+    $removed_foreign_functions,
 );
 
 uksort($new_local, static fn($a, $b) => strtolower($a) <=> strtolower($b));
@@ -51,16 +55,3 @@
 
     echo '],' . "\n";
 }
-
-
-function get_changed_functions(array $a, array $b) {
-    $changed_functions = [];
-
-    foreach (array_intersect_key($a, $b) as $function_name => $a_data) {
-        if (json_encode($b[$function_name]) !== json_encode($a_data)) {
-            $changed_functions[$function_name] = $b[$function_name];
-        }
-    }
-
-    return $changed_functions;
-}

composer.json

@@ -129,6 +129,16 @@
             "@cs",
             "@psalm",
             "@phpunit"
+        ],
+        "gen_callmap": "./bin/stubs/gen_callmap.sh",
+        "gen_propertymap": "@php ./bin/stubs/update-property-map.php",
+        "generate_issues_list_doc": "@php ./bin/docs/generate_issues_list_doc.php",
+        "generate_levels_doc": "@php ./bin/docs/generate_levels_doc.php",
+        "build": [
+            "@gen_callmap",
+            "@gen_propertymap",
+            "@generate_issues_list_doc",
+            "@generate_levels_doc"
         ]
     },
     "scripts-descriptions": {
@@ -138,7 +148,8 @@
         "phpunit": "Runs unit tests in parallel.",
         "phpunit-std": "Runs unit tests.",
         "psalm": "Runs static analysis.",
-        "tests": "Runs all available tests."
+        "tests": "Runs all available tests.",
+        "build": "Generates all autogenerated files."
     },
     "support": {
         "docs": "https://psalm.dev/docs",

src/Psalm/Internal/VersionUtils.php

@@ -40,7 +40,7 @@ public static function getPhpParserVersion(): string
         return self::getVersions()[self::PHP_PARSER_PACKAGE];
     }
 
-    /** @psalm-suppress UnusedMethod called from bin/build-phar.sh */
+    /** @psalm-suppress UnusedMethod called from bin/ci/build-phar.sh */
     public static function dump(): void
     {
         $versions = self::loadComposerVersions();

tests/DocumentationTest.php

@@ -433,7 +433,7 @@ protected function failureDescription(mixed $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.
+     * issues.md can be generated automatically with bin/docs/generate_documentation_issues_list.php.
      */
     public function testIssuesIndex(): void
     {