refactor: Refactor file headers and add Psalm suppressions

- Added Psalm suppression annotations to multiple controller classes
- Added PHPDoc comment blocks to seeders and factories
- Added comments to indicate unused classes and methods
- Removed unused annotations and imports

app/Console/Commands/MigratePlaceDataFromPostgis.php

@@ -8,6 +8,7 @@ use Illuminate\Support\Facades\DB;
 
 /**
  * @codeCoverageIgnore
+ * @psalm-suppress UnusedClass
  */
 class MigratePlaceDataFromPostgis extends Command
 {

app/Console/Commands/ParseCachedWebMentions.php

@@ -9,6 +9,9 @@ use Illuminate\Console\Command;
 use Illuminate\Contracts\Filesystem\FileNotFoundException;
 use Illuminate\FileSystem\FileSystem;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ParseCachedWebMentions extends Command
 {
     /**

app/Console/Commands/ReDownloadWebMentions.php

@@ -8,6 +8,9 @@ use App\Jobs\DownloadWebMention;
 use App\Models\WebMention;
 use Illuminate\Console\Command;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ReDownloadWebMentions extends Command
 {
     /**

app/Http/Controllers/Admin/ArticlesController.php

@@ -9,6 +9,9 @@ use App\Models\Article;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ArticlesController extends Controller
 {
     public function index(): View

app/Http/Controllers/Admin/BioController.php

@@ -10,6 +10,9 @@ use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class BioController extends Controller
 {
     public function show(): View

app/Http/Controllers/Admin/ClientsController.php

@@ -9,6 +9,9 @@ use App\Models\MicropubClient;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ClientsController extends Controller
 {
     /**

app/Http/Controllers/Admin/ContactsController.php

@@ -12,6 +12,9 @@ use Illuminate\Http\RedirectResponse;
 use Illuminate\Support\Arr;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ContactsController extends Controller
 {
     /**

app/Http/Controllers/Admin/HomeController.php

@@ -7,6 +7,9 @@ namespace App\Http\Controllers\Admin;
 use App\Http\Controllers\Controller;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class HomeController extends Controller
 {
     /**

app/Http/Controllers/Admin/LikesController.php

@@ -10,6 +10,9 @@ use App\Models\Like;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class LikesController extends Controller
 {
     /**

app/Http/Controllers/Admin/NotesController.php

@@ -11,6 +11,9 @@ use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class NotesController extends Controller
 {
     /**

app/Http/Controllers/Admin/PlacesController.php

@@ -10,6 +10,9 @@ use App\Services\PlaceService;
 use Illuminate\Http\RedirectResponse;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class PlacesController extends Controller
 {
     protected PlaceService $placeService;

app/Http/Controllers/Admin/SyndicationTargetsController.php

@@ -10,6 +10,9 @@ use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class SyndicationTargetsController extends Controller
 {
     /**

app/Http/Controllers/ArticlesController.php

@@ -10,6 +10,9 @@ use Illuminate\Http\RedirectResponse;
 use Illuminate\View\View;
 use Jonnybarnes\IndieWeb\Numbers;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ArticlesController extends Controller
 {
     /**

app/Http/Controllers/AuthController.php

@@ -9,6 +9,9 @@ use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class AuthController extends Controller
 {
     /**

app/Http/Controllers/BookmarksController.php

@@ -7,6 +7,9 @@ namespace App\Http\Controllers;
 use App\Models\Bookmark;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class BookmarksController extends Controller
 {
     /**

app/Http/Controllers/ContactsController.php

@@ -8,6 +8,9 @@ use App\Models\Contact;
 use Illuminate\Filesystem\Filesystem;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ContactsController extends Controller
 {
     /**

app/Http/Controllers/FeedsController.php

@@ -9,6 +9,9 @@ use App\Models\Note;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Response;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class FeedsController extends Controller
 {
     /**

app/Http/Controllers/FrontPageController.php

@@ -10,6 +10,9 @@ use App\Models\Note;
 use Illuminate\Http\Response;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class FrontPageController extends Controller
 {
     /**

app/Http/Controllers/LikesController.php

@@ -7,6 +7,9 @@ namespace App\Http\Controllers;
 use App\Models\Like;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class LikesController extends Controller
 {
     /**

app/Http/Controllers/MicropubController.php

@@ -19,6 +19,9 @@ use Lcobucci\JWT\Validation\RequiredConstraintsViolated;
 use Monolog\Handler\StreamHandler;
 use Monolog\Logger;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class MicropubController extends Controller
 {
     protected TokenService $tokenService;

app/Http/Controllers/MicropubMediaController.php

@@ -24,6 +24,9 @@ use Lcobucci\JWT\Token\InvalidTokenStructure;
 use Lcobucci\JWT\Validation\RequiredConstraintsViolated;
 use Ramsey\Uuid\Uuid;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class MicropubMediaController extends Controller
 {
     protected TokenService $tokenService;

app/Http/Controllers/NotesController.php

@@ -13,14 +13,16 @@ use Illuminate\Http\Response;
 use Illuminate\View\View;
 use Jonnybarnes\IndieWeb\Numbers;
 
-// Need to sort out Twitter and webmentions!
-
+/**
+ * @todo Need to sort out Twitter and webmentions!
+ * @psalm-suppress UnusedClass
+ */
 class NotesController extends Controller
 {
     /**
      * Show all the notes. This is also the homepage.
      */
-    public function index(Request $request): View|Response
+    public function index(): View|Response
     {
         $notes = Note::latest()
             ->with('place', 'media', 'client')

app/Http/Controllers/PlacesController.php

@@ -7,6 +7,9 @@ namespace App\Http\Controllers;
 use App\Models\Place;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class PlacesController extends Controller
 {
     /**

app/Http/Controllers/SearchController.php

@@ -6,6 +6,9 @@ use App\Models\Note;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class SearchController extends Controller
 {
     public function search(Request $request): View

app/Http/Controllers/ShortURLsController.php

@@ -6,6 +6,9 @@ namespace App\Http\Controllers;
 
 use Illuminate\Http\RedirectResponse;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class ShortURLsController extends Controller
 {
     /*

app/Http/Controllers/TokenEndpointController.php

@@ -12,6 +12,9 @@ use Illuminate\Http\Request;
 use IndieAuth\Client;
 use JsonException;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class TokenEndpointController extends Controller
 {
     /**

app/Http/Controllers/WebMentionsController.php

@@ -12,6 +12,9 @@ use Illuminate\Http\Response;
 use Illuminate\View\View;
 use Jonnybarnes\IndieWeb\Numbers;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class WebMentionsController extends Controller
 {
     /**

app/Http/Middleware/CSPHeader.php

@@ -11,6 +11,8 @@ class CSPHeader
 {
     /**
      * Handle an incoming request.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function handle(Request $request, Closure $next): Response
     {

app/Http/Middleware/CorsHeaders.php

@@ -10,6 +10,8 @@ class CorsHeaders
 {
     /**
      * Handle an incoming request.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function handle(Request $request, Closure $next): Response
     {

app/Http/Middleware/LinkHeadersMiddleware.php

@@ -10,6 +10,8 @@ class LinkHeadersMiddleware
 {
     /**
      * Handle an incoming request.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function handle(Request $request, Closure $next): Response
     {

app/Http/Middleware/LocalhostSessionMiddleware.php

@@ -14,6 +14,8 @@ class LocalhostSessionMiddleware
      * Whilst we are developing locally, automatically log in as
      * `['me' => config('app.url')]` as I can’t manually log in as
      * a .localhost domain.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function handle(Request $request, Closure $next): Response
     {

app/Http/Middleware/MyAuthMiddleware.php

@@ -13,6 +13,8 @@ class MyAuthMiddleware
 {
     /**
      * Check the user is logged in.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function handle(Request $request, Closure $next): Response
     {

app/Http/Middleware/ValidateSignature.php

@@ -10,6 +10,7 @@ class ValidateSignature extends Middleware
      * The names of the query string parameters that should be ignored.
      *
      * @var array<int, string>
+     * @psalm-suppress PossiblyUnusedProperty
      */
     protected $except = [
         // 'fbclid',

app/Http/Middleware/VerifyMicropubToken.php

@@ -12,6 +12,8 @@ class VerifyMicropubToken
 {
     /**
      * Handle an incoming request.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function handle(Request $request, Closure $next): Response
     {

app/Observers/NoteObserver.php

@@ -9,10 +9,15 @@ use App\Models\Tag;
 use Illuminate\Support\Arr;
 use Illuminate\Support\Collection;
 
+/**
+ * @todo Do we need psalm-suppress for these observer methods?
+ */
 class NoteObserver
 {
     /**
      * Listen to the Note created event.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function created(Note $note): void
     {
@@ -35,6 +40,8 @@ class NoteObserver
 
     /**
      * Listen to the Note updated event.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function updated(Note $note): void
     {
@@ -59,6 +66,8 @@ class NoteObserver
 
     /**
      * Listen to the Note deleting event.
+     *
+     * @psalm-suppress PossiblyUnusedMethod
      */
     public function deleting(Note $note): void
     {

app/Providers/HorizonServiceProvider.php

@@ -6,6 +6,9 @@ use Illuminate\Support\Facades\Gate;
 use Laravel\Horizon\Horizon;
 use Laravel\Horizon\HorizonApplicationServiceProvider;
 
+/**
+ * @psalm-suppress UnusedClass
+ */
 class HorizonServiceProvider extends HorizonApplicationServiceProvider
 {
     /**