Improve type coverage

RELEASE_NOTES.md

@@ -21,6 +21,8 @@ This serves two purposes:
 - Updated the realtime compiler to generate the documentation search index each time it's requested in https://github.com/hydephp/develop/pull/1405 (fixes https://github.com/hydephp/develop/issues/1404)
 - Updated the navigation menu generator to remove duplicates after running the sorting method in https://github.com/hydephp/develop/pull/1407 (fixes https://github.com/hydephp/develop/issues/1406)
 - Updated the exception message caused by missing source option for featured images to include the path of the file that caused the error in https://github.com/hydephp/develop/pull/1409
+- Narrows down parsed `BladeMatter` array types to `array<string, scalar>` (Experimental feature not covered by BC promise) in https://github.com/hydephp/develop/pull/1410
+- Internal code refactors and improvements in https://github.com/hydephp/develop/pull/1410
 
 ### Deprecated
 - for soon-to-be removed features.

packages/framework/src/Console/Commands/PublishHomepageCommand.php

@@ -31,6 +31,7 @@ class PublishHomepageCommand extends Command
     /** @var string */
     protected $description = 'Publish one of the default homepages to index.blade.php.';
 
+    /** @var array<string, array{name: string, description: string, group: string}> */
     protected array $options = [
         'welcome'=> [
             'name' => 'Welcome',
@@ -96,6 +97,7 @@ protected function formatPublishableChoices(): array
         })->values()->toArray();
     }
 
+    /** @return Collection<array{name: string, description: string, group: string}> */
     protected function getTemplateOptions(): Collection
     {
         return new Collection($this->options);

packages/framework/src/Facades/Filesystem.php

@@ -63,7 +63,7 @@ public static function relativePath(string $path): string
      *
      * @param  string  $pattern
      * @param  int  $flags
-     * @return \Illuminate\Support\Collection<string>
+     * @return \Illuminate\Support\Collection<int, string>
      */
     public static function smartGlob(string $pattern, int $flags = 0): Collection
     {

packages/framework/src/Foundation/Kernel/Filesystem.php

@@ -65,6 +65,8 @@ public function path(string $path = ''): string
      * Get an absolute file path from a supplied relative path.
      *
      * Input types are matched, meaning that if the input is a string so will the output be.
+     *
+     * @param  string|array<string>  $path
      */
     public function pathToAbsolute(string|array $path): string|array
     {
@@ -143,6 +145,8 @@ public function vendorPath(string $path = '', string $package = 'framework'): st
 
     /**
      * Touch one or more files in the project's directory.
+     *
+     * @param  string|array<string>  $path
      */
     public function touch(string|array $path): bool
     {
@@ -159,6 +163,8 @@ public function touch(string|array $path): bool
 
     /**
      * Unlink one or more files in the project's directory.
+     *
+     * @param  string|array<string>  $path
      */
     public function unlink(string|array $path): bool
     {
@@ -185,9 +191,11 @@ public function unlinkIfExists(string $path): bool
         return false;
     }
 
+    /** @return \Illuminate\Support\Collection<int, string> */
     public function smartGlob(string $pattern, int $flags = 0): Collection
     {
         return collect(\Hyde\Facades\Filesystem::glob($pattern, $flags))
-            ->map(fn (string $path): string => $this->pathToRelative($path));
+            ->map(fn (string $path): string => $this->pathToRelative($path))
+            ->values();
     }
 }

packages/framework/src/Framework/Actions/BladeMatterParser.php

@@ -121,6 +121,7 @@ protected static function extractValue(string $line): string
         return trim($key);
     }
 
+    /** @return scalar|array<string, scalar> */
     protected static function getValueWithType(string $value): mixed
     {
         $value = trim($value);
@@ -138,6 +139,7 @@ protected static function getValueWithType(string $value): mixed
         return json_decode($value) ?? $value;
     }
 
+    /** @return array<string, scalar> */
     protected static function parseArrayString(string $string): array
     {
         $array = [];
@@ -167,7 +169,9 @@ protected static function parseArrayString(string $string): array
             $pair = explode('=>', $token);
 
             // Add key/value pair to array
-            $array[static::getValueWithType(trim(trim($pair[0]), "'"))] = static::getValueWithType(trim(trim($pair[1]), "'"));
+            $key = (string) static::getValueWithType(trim(trim($pair[0]), "'"));
+            $value = static::getValueWithType(trim(trim($pair[1]), "'"));
+            $array[$key] = $value;
         }
 
         return $array;

packages/framework/src/Framework/Actions/PreBuildTasks/CleanSiteDirectory.php

@@ -57,8 +57,10 @@ protected function askIfUnsafeDirectoryShouldBeEmptied(): bool
         ));
     }
 
+    /** @return array<string> */
     protected function safeOutputDirectories(): array
     {
+        /** @var array<string> $directories */
         return Config::getArray('hyde.safe_output_directories', ['_site', 'docs', 'build']);
     }
 }

packages/framework/src/Framework/Factories/NavigationDataFactory.php

@@ -201,6 +201,7 @@ protected function getSubdirectoryConfiguration(): string
         return Config::getString('hyde.navigation.subdirectories', 'hidden');
     }
 
+    /** @param class-string $class */
     protected function isInstanceOf(string $class): bool
     {
         return is_a($this->pageClass, $class, true);

packages/framework/src/Framework/Features/Metadata/MetadataBag.php

@@ -20,9 +20,16 @@
  */
 class MetadataBag implements Htmlable
 {
+    /** @var array<string, MetadataElementContract> */
     protected array $links = [];
+
+    /** @var array<string, MetadataElementContract> */
     protected array $metadata = [];
+
+    /** @var array<string, MetadataElementContract> */
     protected array $properties = [];
+
+    /** @var array<string> */
     protected array $generics = [];
 
     public function toHtml(): string
@@ -59,7 +66,7 @@ public function add(MetadataElementContract|string $element): static
             return $this->addElement('properties', $element);
         }
 
-        return $this->addGenericElement($element);
+        return $this->addGenericElement((string) $element);
     }
 
     protected function addElement(string $type, MetadataElementContract $element): static
@@ -76,12 +83,15 @@ protected function addGenericElement(string $element): static
         return $this;
     }
 
+    /** @return array<string, MetadataElementContract> */
     protected function getPrefixedArray(string $type): array
     {
+        /** @var array<string, MetadataElementContract> $bag */
+        $bag = $this->{$type};
+
         $array = [];
 
-        /** @var MetadataElementContract $element */
-        foreach ($this->{$type} as $key => $element) {
+        foreach ($bag as $key => $element) {
             $array["$type:$key"] = $element;
         }
 

packages/framework/src/Framework/Features/Navigation/DropdownNavItem.php

@@ -26,22 +26,27 @@ public function __construct(string $label, array $items, ?int $priority = null)
         $this->items = $items;
     }
 
+    /** @param array<NavItem> $items */
     public static function fromArray(string $name, array $items): static
     {
         return new static($name, $items);
     }
 
+    /** @return Collection<NavItem> */
     public function getItems(): Collection
     {
         return collect($this->items);
     }
 
     private function searchForDropdownPriorityInNavigationConfig(string $groupKey): ?int
     {
-        return Config::getArray('hyde.navigation.order', [
+        /** @var array<string, int> $config */
+        $config = Config::getArray('hyde.navigation.order', [
             'index' => 0,
             'posts' => 10,
             'docs/index' => 100,
-        ])[$groupKey] ?? null;
+        ]);
+
+        return $config[$groupKey] ?? null;
     }
 }

packages/framework/src/Framework/Services/BuildTaskService.php

@@ -42,7 +42,7 @@ public function __construct()
     {
         $this->registerFrameworkTasks();
 
-        $this->registerTasks(Config::getArray('hyde.build_tasks', []));
+        $this->registerTasks($this->findTasksInConfig());
 
         $this->registerTasks($this->findTasksInAppDirectory());
     }
@@ -52,7 +52,7 @@ public function setOutput(?OutputStyle $output): void
         $this->output = $output;
     }
 
-    /** @return array<class-string<\Hyde\Framework\Features\BuildTasks\BuildTask>> */
+    /** @return array<class-string<\Hyde\Framework\Features\BuildTasks\PreBuildTask>|class-string<\Hyde\Framework\Features\BuildTasks\PostBuildTask>> */
     public function getRegisteredTasks(): array
     {
         return array_map(fn (BuildTask $task): string => $task::class, array_values($this->buildTasks));
@@ -87,20 +87,29 @@ protected function registerTaskInService(PreBuildTask|PostBuildTask $task): void
         $this->buildTasks[$this->makeTaskIdentifier($task)] = $task;
     }
 
+    /** @param class-string<\Hyde\Framework\Features\BuildTasks\PreBuildTask|\Hyde\Framework\Features\BuildTasks\PostBuildTask> $task */
     protected function registerIf(string $task, bool $condition): void
     {
         if ($condition) {
             $this->registerTask($task);
         }
     }
 
+    /** @param array<\Hyde\Framework\Features\BuildTasks\PreBuildTask|\Hyde\Framework\Features\BuildTasks\PostBuildTask|class-string<\Hyde\Framework\Features\BuildTasks\PreBuildTask|\Hyde\Framework\Features\BuildTasks\PostBuildTask>> $tasks */
     protected function registerTasks(array $tasks): void
     {
         foreach ($tasks as $task) {
             $this->registerTask($task);
         }
     }
 
+    /** @return array<class-string<\Hyde\Framework\Features\BuildTasks\PreBuildTask>|class-string<\Hyde\Framework\Features\BuildTasks\PostBuildTask>> */
+    protected function findTasksInConfig(): array
+    {
+        return Config::getArray('hyde.build_tasks', []);
+    }
+
+    /** @return array<class-string<\Hyde\Framework\Features\BuildTasks\PreBuildTask>|class-string<\Hyde\Framework\Features\BuildTasks\PostBuildTask>> */
     protected function findTasksInAppDirectory(): array
     {
         return Filesystem::smartGlob('app/Actions/*BuildTask.php')->map(function (string $file): string {