docs: finalize repository hardening docs and comment compliance

Agent-Logs-Url: https://github.com/Starisian-Technologies/sparxstar-user-environment-check/sessions/e2409563-64b1-463f-aaa1-f61cc5d05cd8

Co-authored-by: MaximillianGroup <34328348+MaximillianGroup@users.noreply.github.com>

Author: Copilot

assets/js/sparxstar-user-environment-check-app.bundle.min.js

@@ -122,7 +122,7 @@ public static function getDeviceHash(): string
     /**
      * Retrieve the latest stored snapshot for a user/session (public).
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      * @return array<string, mixed>|null Snapshot payload when available.
      */
@@ -134,7 +134,7 @@ public static function get_snapshot(?int $user_id = null, ?string $session_id =
     /**
      * Internal engine fetching snapshot from runtime cache/session/cache/DB.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      * @return array<string, mixed>|null Snapshot payload when available.
      */
@@ -185,9 +185,9 @@ private static function fetch_snapshot(?int $user_id, ?string $session_id): ?arr
     /**
      * Generic dot-path accessor into snapshot structure.
      *
-     * @param string $path Dot-path into snapshot array.
-     * @param mixed $default Default value when missing.
-     * @param int|null $user_id Optional user scope.
+     * @param string      $path Dot-path into snapshot array.
+     * @param mixed       $default Default value when missing.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      * @return mixed Resolved value or default.
      */
@@ -217,7 +217,7 @@ private static function get_value_from_snapshot(
     /**
      * Flushes the cache for a given user, forcing the next getter call to fetch fresh data.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function flush_cache(?int $user_id = null, ?string $session_id = null): void
@@ -239,7 +239,7 @@ public static function flush_cache(?int $user_id = null, ?string $session_id = n
     /**
      * Retrieves the entire raw snapshot for debugging or full-data use cases.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      * @return array<string, mixed>|null Snapshot payload when available.
      */
@@ -258,7 +258,7 @@ public static function get_full_snapshot(?int $user_id = null, ?string $session_
      * Get the user's stable, anonymous browser fingerprint ID from the snapshot.
      * This is the primary key for tracking anonymous users.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_visitor_id(?int $user_id = null, ?string $session_id = null): string
@@ -276,7 +276,7 @@ public static function get_visitor_id(?int $user_id = null, ?string $session_id
     /**
      * Retrieve effective network type from the latest snapshot.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_network_type(?int $user_id = null, ?string $session_id = null): string
@@ -292,7 +292,7 @@ public static function get_network_type(?int $user_id = null, ?string $session_i
     /**
      * Determine whether data-saver mode is enabled in snapshot data.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function is_data_saver_enabled(?int $user_id = null, ?string $session_id = null): bool
@@ -308,7 +308,7 @@ public static function is_data_saver_enabled(?int $user_id = null, ?string $sess
     /**
      * Get normalized device type from snapshot.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_user_device(?int $user_id = null, ?string $session_id = null): string
@@ -324,7 +324,7 @@ public static function get_user_device(?int $user_id = null, ?string $session_id
     /**
      * Get GPU identifier from snapshot fingerprinting data.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_user_gpu(?int $user_id = null, ?string $session_id = null): string
@@ -340,7 +340,7 @@ public static function get_user_gpu(?int $user_id = null, ?string $session_id =
     /**
      * Get operating system label from snapshot.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_os_name(?int $user_id = null, ?string $session_id = null): string
@@ -356,7 +356,7 @@ public static function get_os_name(?int $user_id = null, ?string $session_id = n
     /**
      * Get browser name from snapshot.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_browser_name(?int $user_id = null, ?string $session_id = null): string
@@ -374,7 +374,7 @@ public static function get_browser_name(?int $user_id = null, ?string $session_i
     /**
      * Get server-observed user IP from snapshot.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_user_ip(?int $user_id = null, ?string $session_id = null): string
@@ -390,7 +390,7 @@ public static function get_user_ip(?int $user_id = null, ?string $session_id = n
     /**
      * Get user country from snapshot geolocation block.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_user_country(?int $user_id = null, ?string $session_id = null): string
@@ -406,7 +406,7 @@ public static function get_user_country(?int $user_id = null, ?string $session_i
     /**
      * Get user region/state from snapshot geolocation block.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_user_state(?int $user_id = null, ?string $session_id = null): string
@@ -422,7 +422,7 @@ public static function get_user_state(?int $user_id = null, ?string $session_id
     /**
      * Get user city from snapshot geolocation block.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_user_city(?int $user_id = null, ?string $session_id = null): string
@@ -438,7 +438,7 @@ public static function get_user_city(?int $user_id = null, ?string $session_id =
     /**
      * Get two-letter language code from snapshot context language.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_user_language(?int $user_id = null, ?string $session_id = null): string
@@ -458,7 +458,7 @@ public static function get_user_language(?int $user_id = null, ?string $session_
     /**
      * Get UTC timestamp of the stored snapshot.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function get_snapshot_timestamp(?int $user_id = null, ?string $session_id = null): string
@@ -474,7 +474,7 @@ public static function get_snapshot_timestamp(?int $user_id = null, ?string $ses
     /**
      * Determine if geolocation data flagged VPN/proxy usage.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      */
     public static function is_on_vpn(?int $user_id = null, ?string $session_id = null): bool
@@ -500,7 +500,7 @@ public static function get_current_user_session_id(): string
     /**
      * Get full geolocation payload from snapshot server block.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
      * @return array<string, mixed> Geolocation map.
      */
@@ -519,9 +519,9 @@ public static function get_geolocation(?int $user_id = null, ?string $session_id
     /**
      * Geolocation convenience accessor for city.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
-     * @param string $default Default when value is missing.
+     * @param string      $default Default when value is missing.
      */
     public static function get_city(
         ?int $user_id = null,
@@ -539,9 +539,9 @@ public static function get_city(
     /**
      * Geolocation convenience accessor for state.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
-     * @param string $default Default when value is missing.
+     * @param string      $default Default when value is missing.
      */
     public static function get_state(
         ?int $user_id = null,
@@ -559,9 +559,9 @@ public static function get_state(
     /**
      * Geolocation convenience accessor for postal code.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
-     * @param string $default Default when value is missing.
+     * @param string      $default Default when value is missing.
      */
     public static function get_postal_code(
         ?int $user_id = null,
@@ -579,9 +579,9 @@ public static function get_postal_code(
     /**
      * Geolocation convenience accessor for region.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
-     * @param string $default Default when value is missing.
+     * @param string      $default Default when value is missing.
      */
     public static function get_region(
         ?int $user_id = null,
@@ -599,9 +599,9 @@ public static function get_region(
     /**
      * Geolocation convenience accessor for country.
      *
-     * @param int|null $user_id Optional user scope.
+     * @param int|null    $user_id Optional user scope.
      * @param string|null $session_id Optional session scope.
-     * @param string $default Default when value is missing.
+     * @param string      $default Default when value is missing.
      */
     public static function get_country(
         ?int $user_id = null,
@@ -746,7 +746,7 @@ public static function get_current_visitor_ip(): string
      * Persist an arbitrary value in the session namespace.
      *
      * @param string $key Session key.
-     * @param mixed $value Value to persist.
+     * @param mixed  $value Value to persist.
      */
     public static function setSessionValue(string $key, mixed $value): void
     {
@@ -758,7 +758,7 @@ public static function setSessionValue(string $key, mixed $value): void
      * Retrieve a value from the session namespace.
      *
      * @param string $key Session key.
-     * @param mixed $default Default return when missing.
+     * @param mixed  $default Default return when missing.
      * @return mixed Resolved session value.
      */
     public static function getSessionValue(string $key, mixed $default = null): mixed

src/StarUserEnv.php

@@ -8,6 +8,7 @@
  * @copyright Copyright (c) 2023-2026, Starisian Technologies
  * @license Proprietary. All Rights Reserved.
  */
+
 declare(strict_types=1);
 
 namespace Starisian\SparxstarUEC\admin;

src/admin/SparxstarUECAdmin.php

@@ -9,6 +9,7 @@
  * @copyright Copyright (c) 2023-2026, Starisian Technologies
  * @license Proprietary. All Rights Reserved.
  */
+
 declare(strict_types=1);
 
 namespace Starisian\SparxstarUEC\api;

src/api/SparxstarUECRESTController.php

@@ -8,6 +8,7 @@
  * @copyright Copyright (c) 2023-2026, Starisian Technologies
  * @license Proprietary. All Rights Reserved.
  */
+
 declare(strict_types=1);
 
 namespace Starisian\SparxstarUEC\core;

src/core/SparxstarUECAssetManager.php

@@ -8,6 +8,7 @@
  * @copyright Copyright (c) 2023-2026, Starisian Technologies
  * @license Proprietary. All Rights Reserved.
  */
+
 declare(strict_types=1);
 
 namespace Starisian\SparxstarUEC\core;

src/core/SparxstarUECDatabase.php

@@ -9,6 +9,7 @@
  * @copyright Copyright (c) 2023-2026, Starisian Technologies
  * @license Proprietary. All Rights Reserved.
  */
+
 declare(strict_types=1);
 
 namespace Starisian\SparxstarUEC\core;

src/core/SparxstarUECInstaller.php

@@ -20,6 +20,9 @@
 
 use Starisian\SparxstarUEC\helpers\StarLogger;
 
+/**
+ * Snapshot read repository for identity-keyed and admin user lookups.
+ */
 final class SparxstarUECSnapshotRepository
 {
     /**

src/core/SparxstarUECSnapshotRepository.php

@@ -9,6 +9,7 @@
  * @copyright Copyright (c) 2023-2026, Starisian Technologies
  * @license Proprietary. All Rights Reserved.
  */
+
 declare(strict_types=1);
 
 namespace Starisian\SparxstarUEC\cron;
@@ -28,8 +29,8 @@ final class SparxstarUECScheduler
      * Schedule a recurring event safely.
      *
      * @param string $hook The action hook to execute.
-     * @param int $interval_in_seconds How often to run (e.g., 3600, 86400).
-     * @param array $args Arguments to pass to the hook.
+     * @param int    $interval_in_seconds How often to run (e.g., 3600, 86400).
+     * @param array  $args Arguments to pass to the hook.
      */
     public static function schedule_recurring(string $hook, int $interval_in_seconds, array $args = []): void
     {
@@ -78,7 +79,7 @@ public static function schedule_recurring(string $hook, int $interval_in_seconds
     /**
      * Clear all queued instances of a hook.
      *
-     * @param string $hook Scheduled action hook name.
+     * @param string                   $hook Scheduled action hook name.
      * @param array<int|string, mixed> $args Optional hook argument signature.
      */
     public static function clear(string $hook, array $args = []): void