search: add support for alternate sorting

By default the unified sort endpoint will continue to return the results
without additional sorting. However, for usability tests for the search
results sort order, we want to expose a query param that will allow the
caller to specify an alternative sorting algorithm.

To keep it simple, we are exposing only two options for now:

  - `alphabetic`: A-Z on the title attribute.
  - `weighted_index`: custom algorithm to give more weight to different
    types of matches - this algorithm is a work-in-progress.

This code was intentionally made to be easily reverted as we may not
want to expose sorting options in the final implementation.

CMK-24563

Co-authored-by: Benjamin Knapp <benjamin.knapp@checkmk.com>
Change-Id: I25d1cb5120b58ea6eb69caf1ef79687ba4e91379

Author: logan-connolly

cmk/gui/search/pages.py

@@ -6,7 +6,7 @@
 
 from .engines.monitoring import MonitoringSearchEngine
 from .engines.setup import SetupSearchEngine
-from .type_defs import Provider
+from .type_defs import Provider, SortType
 from .unified import UnifiedSearch
 
 
@@ -15,12 +15,18 @@ class PageUnifiedSearch(AjaxPage):
     def page(self, config: Config) -> PageResult:
         query = request.get_str_input_mandatory("q")
         provider = self._parse_provider_query_param()
+        sort_type = self._parse_sort_query_param()
 
         setup_engine = SetupSearchEngine()
         monitoring_engine = MonitoringSearchEngine()
         unified_search_engine = UnifiedSearch(setup_engine, monitoring_engine)
 
-        response = unified_search_engine.search(query, config=config, provider=provider)
+        response = unified_search_engine.search(
+            query,
+            config=config,
+            provider=provider,
+            sort_type=sort_type,
+        )
 
         return {
             "url": request.url,
@@ -34,3 +40,9 @@ def _parse_provider_query_param(self) -> Provider | None:
             return None
 
         return cast(Provider, provider) if provider in get_args(Provider) else None
+
+    def _parse_sort_query_param(self) -> SortType | None:
+        if (sort_type := request.get_str_input("sort")) is None:
+            return None
+
+        return cast(SortType, sort_type) if sort_type in get_args(SortType) else None

cmk/gui/search/sorting.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+# Copyright (C) 2025 Checkmk GmbH - License: GNU General Public License v2
+# This file is part of Checkmk (https://checkmk.com). It is subject to the terms and
+# conditions defined in the file COPYING, which is part of this source code package.
+
+from collections.abc import Callable
+
+from .type_defs import SortType, UnifiedSearchResultItem
+
+type Sorter = Callable[[list[UnifiedSearchResultItem]], None]
+
+
+def get_sorter(sort_type: SortType | None, query: str = "") -> Sorter:
+    match sort_type:
+        case "alphabetic":
+            return _get_alphabetical_sorter
+        case "weighted_index":
+            return _get_weighted_index_sorter(query)
+        case _:
+            return _get_no_op_sorter
+
+
+def _get_no_op_sorter(_: list[UnifiedSearchResultItem]) -> None:
+    return None
+
+
+def _get_alphabetical_sorter(items: list[UnifiedSearchResultItem]) -> None:
+    items.sort(key=lambda item: item.title)
+
+
+def _get_weighted_index_sorter(query: str) -> Sorter:
+    def algorithm(item: UnifiedSearchResultItem) -> int:
+        weighting = 5
+        if (title_idx := item.title.lower().find(query)) >= 0:
+            weighting = 1
+            if len(item.title) == len(query):
+                weighting = 0
+
+            if title_idx > 0:
+                weighting = 2
+        else:
+            title_idx = len(item.title)
+
+        return weighting * title_idx
+
+    def sorter(items: list[UnifiedSearchResultItem]) -> None:
+        items.sort(key=lambda item: algorithm(item))
+
+    return sorter

cmk/gui/search/type_defs.py

@@ -9,6 +9,7 @@
 # NOTE: intentionally not using the `type` syntax because it's not possible to use
 # `typing.get_args` to dynamically check if string is type at runtime.
 Provider = Literal["setup", "monitoring"]
+SortType = Literal["alphabetic", "weighted_index"]
 
 
 class UnifiedSearchResultItemSerialized(TypedDict):

cmk/gui/search/unified.py

@@ -11,8 +11,10 @@
 
 from .engines.monitoring import SupportsMonitoringSearchEngine
 from .engines.setup import SupportsSetupSearchEngine
+from .sorting import get_sorter
 from .type_defs import (
     Provider,
+    SortType,
     UnifiedSearchResult,
     UnifiedSearchResultCounts,
     UnifiedSearchResultItem,
@@ -37,6 +39,7 @@ def search(
         *,
         config: Config,
         provider: Provider | None = None,
+        sort_type: SortType | None = None,
     ) -> UnifiedSearchResult:
         setup_results_by_topic: SearchResultsByTopic = []
         monitoring_results_by_topic: SearchResultsByTopic = []
@@ -63,6 +66,7 @@ def search(
             )
         )
         search_results = [*setup_results, *monitoring_results]
+        get_sorter(sort_type, query)(search_results)
 
         result_counts = UnifiedSearchResultCounts(
             total=len(search_results),

tests/unit/cmk/gui/search/__init__.py

@@ -0,0 +1,4 @@
+#!/usr/bin/env python3
+# Copyright (C) 2025 Checkmk GmbH - License: GNU General Public License v2
+# This file is part of Checkmk (https://checkmk.com). It is subject to the terms and
+# conditions defined in the file COPYING, which is part of this source code package.

tests/unit/cmk/gui/search/test_sorting.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+# Copyright (C) 2025 Checkmk GmbH - License: GNU General Public License v2
+# This file is part of Checkmk (https://checkmk.com). It is subject to the terms and
+# conditions defined in the file COPYING, which is part of this source code package.
+
+from cmk.gui.search.sorting import get_sorter
+from cmk.gui.search.type_defs import UnifiedSearchResultItem
+
+
+def get_unsorted_results() -> list[UnifiedSearchResultItem]:
+    return [
+        UnifiedSearchResultItem(title="Beta", url="/beta", provider="setup", topic="Code"),
+        UnifiedSearchResultItem(title="Charlie", url="/charlie", provider="setup", topic="Code"),
+        UnifiedSearchResultItem(title="Alpha", url="/alpha", provider="setup", topic="Code"),
+    ]
+
+
+def test_no_op_sorter() -> None:
+    results = get_unsorted_results()
+    sorter = get_sorter(None)
+    sorter(results)
+
+    assert results == get_unsorted_results()
+
+
+def test_alphabetical_sorter() -> None:
+    results = get_unsorted_results()
+    sorter = get_sorter("alphabetic")
+    sorter(results)
+
+    expected = [
+        UnifiedSearchResultItem(title="Alpha", url="/alpha", provider="setup", topic="Code"),
+        UnifiedSearchResultItem(title="Beta", url="/beta", provider="setup", topic="Code"),
+        UnifiedSearchResultItem(title="Charlie", url="/charlie", provider="setup", topic="Code"),
+    ]
+
+    assert results == expected
+
+
+def test_weighted_sorter() -> None:
+    results = get_unsorted_results()
+    sorter = get_sorter("weighted_index", query="bet")
+    sorter(results)
+
+    expected = [
+        UnifiedSearchResultItem(title="Beta", url="/beta", provider="setup", topic="Code"),
+        UnifiedSearchResultItem(title="Alpha", url="/alpha", provider="setup", topic="Code"),
+        UnifiedSearchResultItem(title="Charlie", url="/charlie", provider="setup", topic="Code"),
+    ]
+
+    assert results == expected