semantics

backend/src/api/routes/datasets.py

@@ -1,7 +1,7 @@
 # #region DatasetsApi [C:5] [TYPE Module] [SEMANTICS fastapi, dataset, api, search, mapping, mapped-fields]
 #
 # @BRIEF API endpoints for the Dataset Hub - listing datasets with mapping progress
-# @LAYER:     API
+# @LAYER     API
 # @RELATION DEPENDS_ON -> [AppDependencies]
 # @RELATION DEPENDS_ON -> [ResourceService]
 # @RELATION DEPENDS_ON -> [SupersetClient]
@@ -10,7 +10,7 @@
 # @POST Returns dataset metadata with mapping status.
 # @SIDE_EFFECT Reads from Superset API and task manager.
 # @DATA_CONTRACT Input -> DatasetQuery, Output -> DatasetsResponse, DatasetDetailResponse
-# @INVARIANT: All dataset responses include last_task metadata
+# @INVARIANT  All dataset responses include last_task metadata
 
 
 import re
@@ -149,9 +149,9 @@ class MetricDescriptionUpdate(BaseModel):
 
 # #region get_dataset_ids [C:4] [TYPE Function]
 # @BRIEF Fetch list of all dataset IDs from a specific environment (without pagination)
-# @PRE: env_id must be a valid environment ID
-# @POST: Returns a list of all dataset IDs
-# @RELATION CALLS -> [get_datasets_with_status]
+# @PRE  env_id must be a valid environment ID
+# @POST  Returns a list of all dataset IDs
+# @RELATION CALLS -> [EXT:method:get_datasets_with_status]
 @router.get("/ids")
 async def get_dataset_ids(
     env_id: str,
@@ -197,13 +197,13 @@ async def get_dataset_ids(
 
 # #region get_datasets [C:4] [TYPE Function]
 # @BRIEF Fetch list of datasets from a specific environment with mapping progress and stats.
-# @PRE: env_id must be a valid environment ID
-# @PRE: page must be >= 1 if provided
-# @PRE: page_size must be between 1 and 100 if provided
-# @POST: Returns a list of datasets with enhanced metadata, pagination info, and StatsCounts.
-# @POST: Response includes pagination metadata (page, page_size, total, total_pages) and stats object.
+# @PRE  env_id must be a valid environment ID
+# @PRE  page must be >= 1 if provided
+# @PRE  page_size must be between 1 and 100 if provided
+# @POST  Returns a list of datasets with enhanced metadata, pagination info, and StatsCounts.
+# @POST  Response includes pagination metadata (page, page_size, total, total_pages) and stats object.
 # @RATIONALE Stats counts returned in the same response as datasets to avoid an extra API call for the Stats Bar (FR-022).
-# @RELATION CALLS -> [get_datasets_with_status]
+# @RELATION CALLS -> [EXT:method:get_datasets_with_status]
 @router.get("", response_model=DatasetsResponse)
 async def get_datasets(
     env_id: str,
@@ -324,11 +324,11 @@ class MapColumnsRequest(BaseModel):
 
 # #region map_columns [C:4] [TYPE Function]
 # @BRIEF Trigger bulk column mapping for datasets
-# @PRE: User has permission plugin:mapper:execute
-# @PRE: env_id is a valid environment ID
-# @PRE: dataset_ids is a non-empty list
-# @POST: Returns task_id for tracking mapping progress
-# @POST: Task is created and queued for execution
+# @PRE  User has permission plugin:mapper:execute
+# @PRE  env_id is a valid environment ID
+# @PRE  dataset_ids is a non-empty list
+# @POST  Returns task_id for tracking mapping progress
+# @POST  Task is created and queued for execution
 # @RELATION DISPATCHES -> [MapperPlugin]
 # @RELATION CALLS -> [create_task]
 @router.post("/map-columns", response_model=TaskResponse)
@@ -397,11 +397,11 @@ class GenerateDocsRequest(BaseModel):
 
 # #region generate_docs [C:4] [TYPE Function]
 # @BRIEF Trigger bulk documentation generation for datasets
-# @PRE: User has permission plugin:llm_analysis:execute
-# @PRE: env_id is a valid environment ID
-# @PRE: dataset_ids is a non-empty list
-# @POST: Returns task_id for tracking documentation generation progress
-# @POST: Task is created and queued for execution
+# @PRE  User has permission plugin:llm_analysis:execute
+# @PRE  env_id is a valid environment ID
+# @PRE  dataset_ids is a non-empty list
+# @POST  Returns task_id for tracking documentation generation progress
+# @POST  Task is created and queued for execution
 # @RELATION DISPATCHES -> [DocumentationPlugin]
 # @RELATION CALLS -> [create_task]
 @router.post("/generate-docs", response_model=TaskResponse)
@@ -450,9 +450,9 @@ async def generate_docs(
 
 # #region get_dataset_detail [C:4] [TYPE Function]
 # @BRIEF Get detailed dataset information including columns and linked dashboards
-# @PRE: env_id is a valid environment ID
-# @PRE: dataset_id is a valid dataset ID
-# @POST: Returns detailed dataset info with columns and linked dashboards
+# @PRE  env_id is a valid environment ID
+# @PRE  dataset_id is a valid dataset ID
+# @POST  Returns detailed dataset info with columns and linked dashboards
 # @RELATION CALLS -> [SupersetClientGetDatasetDetail]
 @router.get("/{dataset_id}", response_model=DatasetDetailResponse)
 async def get_dataset_detail(
@@ -505,13 +505,13 @@ def _strip_html_tags(text: str) -> str:
 
 # #region update_column_description [C:4] [TYPE Endpoint]
 # @BRIEF Save description for a single dataset column. Internal: GET full dataset from Superset, modify one column's description, PUT back.
-# @PRE: dataset_id and column_id must exist in the target environment.
-# @POST: Column description in Superset is updated. Response confirms success.
-# @SIDE_EFFECT: Mutates dataset metadata in upstream Superset instance via PUT.
+# @PRE  dataset_id and column_id must exist in the target environment.
+# @POST  Column description in Superset is updated. Response confirms success.
+# @SIDE_EFFECT  Mutates dataset metadata in upstream Superset instance via PUT.
 # @VALIDATION: description — string, max 2000 chars, plain text only (HTML stripped), may be empty string to clear description, no trimming applied. 404 if dataset or column not found. 502 if Superset upstream fails.
-# @ERROR: 400 — description exceeds max length or contains non-plaintext content. 404 — dataset_id or column_id not found. 502 — Superset upstream failure (GET or PUT).
-# @RELATION CALLS -> [SupersetClient.get_dataset]
-# @RELATION CALLS -> [SupersetClient.update_dataset]
+# @ERROR  400 — description exceeds max length or contains non-plaintext content. 404 — dataset_id or column_id not found. 502 — Superset upstream failure (GET or PUT).
+# @RELATION CALLS -> [EXT:method:SupersetClient.get_dataset]
+# @RELATION CALLS -> [EXT:method:SupersetClient.update_dataset]
 # @RATIONALE Must perform GET→modify→PUT because Superset has no PATCH for individual columns — only full object PUT with override_columns=false.
 # @REJECTED Direct PUT from frontend — rejected because frontend would need to handle full Superset payload structure.
 @router.put("/{dataset_id}/columns/{column_id}/description")
@@ -594,13 +594,13 @@ async def update_column_description(
 
 # #region update_metric_description [C:4] [TYPE Endpoint]
 # @BRIEF Save description for a single dataset metric. Mirror of update_column_description for metrics.
-# @PRE: dataset_id and metric_id must exist in the target environment.
-# @POST: Metric description in Superset is updated.
-# @SIDE_EFFECT: Mutates dataset metadata in upstream Superset instance via PUT.
+# @PRE  dataset_id and metric_id must exist in the target environment.
+# @POST  Metric description in Superset is updated.
+# @SIDE_EFFECT  Mutates dataset metadata in upstream Superset instance via PUT.
 # @VALIDATION: description — string, max 2000 chars, plain text only (HTML stripped), may be empty string to clear description, no trimming applied. 404 if dataset or metric not found. 502 if Superset upstream fails.
-# @ERROR: 400 — description exceeds max length or contains non-plaintext content. 404 — dataset_id or metric_id not found. 502 — Superset upstream failure (GET or PUT).
-# @RELATION CALLS -> [SupersetClient.get_dataset]
-# @RELATION CALLS -> [SupersetClient.update_dataset]
+# @ERROR  400 — description exceeds max length or contains non-plaintext content. 404 — dataset_id or metric_id not found. 502 — Superset upstream failure (GET or PUT).
+# @RELATION CALLS -> [EXT:method:SupersetClient.get_dataset]
+# @RELATION CALLS -> [EXT:method:SupersetClient.update_dataset]
 @router.put("/{dataset_id}/metrics/{metric_id}/description")
 async def update_metric_description(
     dataset_id: int,