refactor(semantics): migrate legacy @TIER to @COMPLEXITY annotations

- Replaced @TIER: TRIVIAL with @COMPLEXITY: 1
- Replaced @TIER: STANDARD with @COMPLEXITY: 3
- Replaced @TIER: CRITICAL with @COMPLEXITY: 5
- Manually elevated specific critical/complex components to levels 2 and 4
- Ignored legacy, specs, and node_modules directories
- Updated generated semantic map

backend/src/core/superset_client.py

@@ -1,6 +1,6 @@
 # [DEF:backend.src.core.superset_client:Module]
 #
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @SEMANTICS: superset, api, client, rest, http, dashboard, dataset, import, export
 # @PURPOSE:   Предоставляет высокоуровневый клиент для взаимодействия с Superset REST API, инкапсулируя логику запросов, обработку ошибок и пагинацию.
 # @LAYER:     Core
@@ -25,13 +25,13 @@ from .config_models import Environment
 # [/SECTION]
 
 # [DEF:backend.src.core.superset_client.SupersetClient:Class]
-# @TIER: STANDARD
+# @COMPLEXITY: 3
 # @PURPOSE: Класс-обёртка над Superset REST API, предоставляющий методы для работы с дашбордами и датасетами.
 # @RELATION: [DEPENDS_ON] ->[backend.src.core.utils.network.APIClient]
 # @RELATION: [DEPENDS_ON] ->[backend.src.core.config_models.Environment]
 class SupersetClient:
     # [DEF:backend.src.core.superset_client.SupersetClient.__init__:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Инициализирует клиент, проверяет конфигурацию и создает сетевой клиент.
     # @PRE:  `env` должен быть валидным объектом Environment.
     # @POST: Атрибуты `env` и `network` созданы и готовы к работе.
@@ -60,7 +60,7 @@ class SupersetClient:
     # [/DEF:__init__:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.authenticate:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Authenticates the client using the configured credentials.
     # @PRE: self.network must be initialized with valid auth configuration.
     # @POST: Client is authenticated and tokens are stored.
@@ -73,7 +73,7 @@ class SupersetClient:
 
     @property
     # [DEF:backend.src.core.superset_client.SupersetClient.headers:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Возвращает базовые HTTP-заголовки, используемые сетевым клиентом.
     # @PRE: APIClient is initialized and authenticated.
     # @POST: Returns a dictionary of HTTP headers.
@@ -85,7 +85,7 @@ class SupersetClient:
     # [SECTION: DASHBOARD OPERATIONS]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dashboards:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Получает полный список дашбордов, автоматически обрабатывая пагинацию.
     # @PRE: Client is authenticated.
     # @POST: Returns a tuple with total count and list of dashboards.
@@ -119,7 +119,7 @@ class SupersetClient:
     # [/DEF:get_dashboards:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dashboards_page:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches a single dashboards page from Superset without iterating all pages.
     # @PRE: Client is authenticated.
     # @POST: Returns total count and one page of dashboards.
@@ -156,7 +156,7 @@ class SupersetClient:
     # [/DEF:get_dashboards_page:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dashboards_summary:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches dashboard metadata optimized for the grid.
     # @PRE: Client is authenticated.
     # @POST: Returns a list of dashboard metadata summaries.
@@ -241,7 +241,7 @@ class SupersetClient:
     # [/DEF:get_dashboards_summary:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dashboards_summary_page:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches one page of dashboard metadata optimized for the grid.
     # @PRE: page >= 1 and page_size > 0.
     # @POST: Returns mapped summaries and total dashboard count.
@@ -314,7 +314,7 @@ class SupersetClient:
     # [/DEF:get_dashboards_summary_page:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._extract_owner_labels:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Normalize dashboard owners payload to stable display labels.
     # @PRE: owners payload can be scalar, object or list.
     # @POST: Returns deduplicated non-empty owner labels preserving order.
@@ -342,7 +342,7 @@ class SupersetClient:
     # [/DEF:_extract_owner_labels:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._extract_user_display:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Normalize user payload to a stable display name.
     # @PRE: user payload can be string, dict or None.
     # @POST: Returns compact non-empty display value or None.
@@ -371,7 +371,7 @@ class SupersetClient:
     # [/DEF:_extract_user_display:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._sanitize_user_text:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Convert scalar value to non-empty user-facing text.
     # @PRE: value can be any scalar type.
     # @POST: Returns trimmed string or None.
@@ -385,7 +385,7 @@ class SupersetClient:
     # [/DEF:_sanitize_user_text:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dashboard:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches a single dashboard by ID.
     # @PRE: Client is authenticated and dashboard_id exists.
     # @POST: Returns dashboard payload from Superset API.
@@ -398,7 +398,7 @@ class SupersetClient:
     # [/DEF:get_dashboard:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_chart:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches a single chart by ID.
     # @PRE: Client is authenticated and chart_id exists.
     # @POST: Returns chart payload from Superset API.
@@ -411,7 +411,7 @@ class SupersetClient:
     # [/DEF:get_chart:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dashboard_detail:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches detailed dashboard information including related charts and datasets.
     # @PRE: Client is authenticated and dashboard_id exists.
     # @POST: Returns dashboard metadata with charts and datasets lists.
@@ -606,7 +606,7 @@ class SupersetClient:
     # [/DEF:get_dashboard_detail:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_charts:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches all charts with pagination support.
     # @PRE: Client is authenticated.
     # @POST: Returns total count and charts list.
@@ -626,7 +626,7 @@ class SupersetClient:
     # [/DEF:get_charts:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._extract_chart_ids_from_layout:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Traverses dashboard layout metadata and extracts chart IDs from common keys.
     # @PRE: payload can be dict/list/scalar.
     # @POST: Returns a set of chart IDs found in nested structures.
@@ -659,7 +659,7 @@ class SupersetClient:
     # [/DEF:_extract_chart_ids_from_layout:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.export_dashboard:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Экспортирует дашборд в виде ZIP-архива.
     # @PRE: dashboard_id must exist in Superset.
     # @POST: Returns ZIP content and filename.
@@ -684,7 +684,7 @@ class SupersetClient:
     # [/DEF:export_dashboard:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.import_dashboard:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Импортирует дашборд из ZIP-файла.
     # @PRE: file_name must be a valid ZIP dashboard export.
     # @POST: Dashboard is imported or re-imported after deletion.
@@ -716,7 +716,7 @@ class SupersetClient:
     # [/DEF:import_dashboard:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.delete_dashboard:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Удаляет дашборд по его ID или slug.
     # @PRE: dashboard_id must exist.
     # @POST: Dashboard is removed from Superset.
@@ -738,7 +738,7 @@ class SupersetClient:
     # [SECTION: DATASET OPERATIONS]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_datasets:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Получает полный список датасетов, автоматически обрабатывая пагинацию.
     # @PRE: Client is authenticated.
     # @POST: Returns total count and list of datasets.
@@ -759,7 +759,7 @@ class SupersetClient:
     # [/DEF:get_datasets:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_datasets_summary:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches dataset metadata optimized for the Dataset Hub grid.
     # @PRE: Client is authenticated.
     # @POST: Returns a list of dataset metadata summaries.
@@ -784,7 +784,7 @@ class SupersetClient:
     # [/DEF:get_datasets_summary:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dataset_detail:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches detailed dataset information including columns and linked dashboards
     # @PRE: Client is authenticated and dataset_id exists.
     # @POST: Returns detailed dataset info with columns and linked dashboards.
@@ -897,7 +897,7 @@ class SupersetClient:
     # [/DEF:get_dataset_detail:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_dataset:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Получает информацию о конкретном датасете по его ID.
     # @PRE: dataset_id must exist.
     # @POST: Returns dataset details.
@@ -913,7 +913,7 @@ class SupersetClient:
     # [/DEF:get_dataset:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.update_dataset:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Обновляет данные датасета по его ID.
     # @PRE: dataset_id must exist.
     # @POST: Dataset is updated in Superset.
@@ -939,7 +939,7 @@ class SupersetClient:
     # [SECTION: DATABASE OPERATIONS]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_databases:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Получает полный список баз данных.
     # @PRE: Client is authenticated.
     # @POST: Returns total count and list of databases.
@@ -962,7 +962,7 @@ class SupersetClient:
     # [/DEF:get_databases:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_database:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Получает информацию о конкретной базе данных по её ID.
     # @PRE: database_id must exist.
     # @POST: Returns database details.
@@ -978,7 +978,7 @@ class SupersetClient:
     # [/DEF:get_database:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_databases_summary:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetch a summary of databases including uuid, name, and engine.
     # @PRE: Client is authenticated.
     # @POST: Returns list of database summaries.
@@ -999,7 +999,7 @@ class SupersetClient:
     # [/DEF:get_databases_summary:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_database_by_uuid:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Find a database by its UUID.
     # @PRE: db_uuid must be a valid UUID string.
     # @POST: Returns database info or None.
@@ -1019,7 +1019,7 @@ class SupersetClient:
     # [SECTION: HELPERS]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._resolve_target_id_for_delete:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Resolves a dashboard ID from either an ID or a slug.
     # @PRE: Either dash_id or dash_slug should be provided.
     # @POST: Returns the resolved ID or None.
@@ -1042,7 +1042,7 @@ class SupersetClient:
     # [/DEF:_resolve_target_id_for_delete:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._do_import:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Performs the actual multipart upload for import.
     # @PRE: file_name must be a path to an existing ZIP file.
     # @POST: Returns the API response from the upload.
@@ -1064,7 +1064,7 @@ class SupersetClient:
     # [/DEF:_do_import:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._validate_export_response:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Validates that the export response is a non-empty ZIP archive.
     # @PRE: response must be a valid requests.Response object.
     # @POST: Raises SupersetAPIError if validation fails.
@@ -1078,7 +1078,7 @@ class SupersetClient:
     # [/DEF:_validate_export_response:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._resolve_export_filename:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Determines the filename for an exported dashboard.
     # @PRE: response must contain Content-Disposition header or dashboard_id must be provided.
     # @POST: Returns a sanitized filename string.
@@ -1094,7 +1094,7 @@ class SupersetClient:
     # [/DEF:_resolve_export_filename:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._validate_query_params:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Ensures query parameters have default page and page_size.
     # @PRE: query can be None or a dictionary.
     # @POST: Returns a dictionary with at least page and page_size.
@@ -1107,7 +1107,7 @@ class SupersetClient:
     # [/DEF:_validate_query_params:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._fetch_total_object_count:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Fetches the total number of items for a given endpoint.
     # @PRE: endpoint must be a valid Superset API path.
     # @POST: Returns the total count as an integer.
@@ -1122,7 +1122,7 @@ class SupersetClient:
     # [/DEF:_fetch_total_object_count:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._fetch_all_pages:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Iterates through all pages to collect all data items.
     # @PRE: pagination_options must contain base_query, total_count, and results_field.
     # @POST: Returns a combined list of all items.
@@ -1132,7 +1132,7 @@ class SupersetClient:
     # [/DEF:_fetch_all_pages:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient._validate_import_file:Function]
-    # @TIER: TRIVIAL
+    # @COMPLEXITY: 1
     # @PURPOSE: Validates that the file to be imported is a valid ZIP with metadata.yaml.
     # @PRE: zip_path must be a path to a file.
     # @POST: Raises error if file is missing, not a ZIP, or missing metadata.
@@ -1149,7 +1149,7 @@ class SupersetClient:
     # [/DEF:_validate_import_file:Function]
 
     # [DEF:backend.src.core.superset_client.SupersetClient.get_all_resources:Function]
-    # @TIER: STANDARD
+    # @COMPLEXITY: 3
     # @PURPOSE: Fetches all resources of a given type with id, uuid, and name columns.
     # @PARAM: resource_type (str) - One of "chart", "dataset", "dashboard".
     # @PRE: Client is authenticated. resource_type is valid.