agent foundation

lib/Support/Search/SearchQueryNormalizer.php

@@ -4,6 +4,8 @@ namespace MintyPHP\Support\Search;
 
 class SearchQueryNormalizer
 {
+    // Prepares a user query for SQL LIKE. Escapes \ and _ (LIKE special chars),
+    // converts * to %, and wraps with % wildcards if not already present.
     public static function normalizeLikeQuery(string $query): string
     {
         $query = trim($query);
@@ -25,6 +27,7 @@ class SearchQueryNormalizer
         return $query;
     }
 
+    // Strips wildcard chars for relevance scoring — score queries need a clean term, not a LIKE pattern.
     public static function normalizeScoreQuery(string $query): string
     {
         $query = trim($query);

lib/Support/Search/SearchSpecialResourceProvider.php

@@ -28,6 +28,8 @@ class SearchSpecialResourceProvider
         return $rows;
     }
 
+    // Two-tier match: first checks against the hotkey service's keyword list (e.g. "shortcut", "keyboard"),
+    // then falls back to substring matching against individual entry labels/key combos.
     private static function matchesHotkeyQueryWith(string $query, array $entries): bool
     {
         $query = trim(mb_strtolower($query));
@@ -222,6 +224,7 @@ class SearchSpecialResourceProvider
                 $descriptionParts[] = $snippet;
             }
 
+            // Map raw doc scores (0–1000+) to coarser search_score buckets for result ranking.
             $rawScore = (int) $match['score'];
             $searchScore = match (true) {
                 $rawScore >= 1000 => 400,

lib/Support/Search/SearchSqlResourceProvider.php

@@ -4,6 +4,8 @@ namespace MintyPHP\Support\Search;
 
 use MintyPHP\Service\Access\PermissionService;
 
+// Defines all SQL-backed search resources. Each resource declares count/preview/result queries
+// with a {{tenantFilter}} placeholder that is substituted at query time based on the user's tenant scope.
 class SearchSqlResourceProvider
 {
     public static function tenantScopeFilters(): array
@@ -25,6 +27,7 @@ class SearchSqlResourceProvider
                 'key' => 'address-book',
                 'label' => t('Address book'),
                 'permission' => PermissionService::ADDRESS_BOOK_VIEW,
+                // escape '\\\\' — four backslashes: PHP reduces to two, SQL reduces to one literal backslash escape char.
                 'countSql' => "select count(*) from users where active = 1 and (first_name like ? escape '\\\\' or last_name like ? escape '\\\\' or email like ? escape '\\\\') {{tenantFilter}}",
                 'countParams' => [$like, $like, $like],
                 'previewSql' => "select uuid, first_name, last_name, email from users where active = 1 and (first_name like ? escape '\\\\' or last_name like ? escape '\\\\' or email like ? escape '\\\\') {{tenantFilter}} order by last_name, first_name limit ?",