docs(phpdoc): document public methods across src/

Add professional PHPDoc (summary + @param/@return) to the remaining
public methods that had none or only partial coverage: GraphController's
actions, ContributionStore's accessors, SvgRenderer's render() and
private helpers (with concrete array-shape annotations), ProbeTrait,
ProviderHealthChecker, ProviderStatus, and the Contribution entity.
Also adds the matching @return shapes on SvgRendererTest's data
providers.

src/Service/ContributionStore.php

@@ -15,6 +15,9 @@ class ContributionStore
 
     /**
      * Opens (creating if needed) the SQLite store at $dbPath and ensures the schema exists.
+     *
+     * @param string $dbPath        filesystem path to the SQLite database file
+     * @param ?int   $retentionDays days of history to keep; null or 0 keeps rows forever
      */
     public function __construct(
         private readonly string $dbPath = "%kernel.project_dir%/var/data/contributions.db",
@@ -43,6 +46,10 @@ class ContributionStore
 
     /**
      * Inserts a contribution count, overwriting any existing count for the same provider/date.
+     *
+     * @param string $provider provider identifier, e.g. "github"
+     * @param int    $unixtime day of the contribution, as a unix timestamp
+     * @param int    $count    contribution count for that day
      */
     public function add(string $provider, int $unixtime, int $count): void
     {
@@ -56,6 +63,9 @@ class ContributionStore
 
     /**
      * Deletes the contribution row for the given provider/date, if any.
+     *
+     * @param string $provider provider identifier, e.g. "github"
+     * @param int    $unixtime day to delete, as a unix timestamp
      */
     public function remove(string $provider, int $unixtime): void
     {
@@ -69,7 +79,8 @@ class ContributionStore
     /**
      * Upserts a batch of date => count pairs for a provider via repeated add() calls.
      *
-     * @param array<int, int> $dateCounts unix timestamp => count
+     * @param string           $provider   provider identifier, e.g. "github"
+     * @param array<int, int>  $dateCounts unix timestamp => count
      */
     public function merge(string $provider, array $dateCounts): void
     {
@@ -80,6 +91,9 @@ class ContributionStore
 
     /**
      * Returns the most recent stored unix timestamp for a provider, or null if it has no rows.
+     *
+     * @param  string $provider provider identifier, e.g. "github"
+     * @return ?int   unix timestamp of the latest stored day, or null if none stored yet
      */
     public function latestDate(string $provider): ?int
     {
@@ -92,6 +106,10 @@ class ContributionStore
 
     /**
      * Returns all stored contributions for a provider, optionally limited to the last $sinceDays days.
+     *
+     * @param  string $provider  provider identifier, e.g. "github"
+     * @param  ?int   $sinceDays if set, only rows from the last N days are returned
+     * @return ContributionCollection
      */
     public function all(string $provider, ?int $sinceDays = null): ContributionCollection
     {
@@ -106,9 +124,12 @@ class ContributionStore
         $stmt = $this->pdo->prepare($sql);
         $stmt->execute($params);
 
+        /** @var array<int, array{provider: string, date: int|string, count: int|string}> $rows */
+        $rows = $stmt->fetchAll(PDO::FETCH_ASSOC);
+
         $contributions = array_map(
             static fn(array $row): Contribution => new Contribution($row['provider'], (int) $row['date'], (int) $row['count']),
-            $stmt->fetchAll(PDO::FETCH_ASSOC),
+            $rows,
         );
 
         return new ContributionCollection(...$contributions);