semantic markup update

2026-01-18 21:29:54 +03:00
parent 11c59fb420
commit 76baeb1038
85 changed files with 7020 additions and 5953 deletions
--- a/backend/src/api/routes/environments.py
+++ b/backend/src/api/routes/environments.py
@@ -43,10 +43,13 @@ class DatabaseResponse(BaseModel):

 # [DEF:get_environments:Function]
 # @PURPOSE: List all configured environments.
+# @PRE:     config_manager is injected via Depends.
+# @POST:    Returns a list of EnvironmentResponse objects.
 # @RETURN:  List[EnvironmentResponse]
@router.get("", response_model=List[EnvironmentResponse])
 async def get_environments(config_manager=Depends(get_config_manager)):
-    envs = config_manager.get_environments()
+    with belief_scope("get_environments"):
+        envs = config_manager.get_environments()
    # Ensure envs is a list
    if not isinstance(envs, list):
        envs = []
@@ -65,6 +68,8 @@ async def get_environments(config_manager=Depends(get_config_manager)):

 # [DEF:update_environment_schedule:Function]
 # @PURPOSE: Update backup schedule for an environment.
+# @PRE:     Environment id exists, schedule is valid ScheduleSchema.
+# @POST:    Backup schedule updated and scheduler reloaded.
 # @PARAM:   id (str) - The environment ID.
 # @PARAM:   schedule (ScheduleSchema) - The new schedule.
@router.put("/{id}/schedule")
@@ -74,7 +79,8 @@ async def update_environment_schedule(
    config_manager=Depends(get_config_manager),
    scheduler_service=Depends(get_scheduler_service)
 ):
-    envs = config_manager.get_environments()
+    with belief_scope("update_environment_schedule", f"id={id}"):
+        envs = config_manager.get_environments()
    env = next((e for e in envs if e.id == id), None)
    if not env:
        raise HTTPException(status_code=404, detail="Environment not found")
@@ -93,11 +99,14 @@ async def update_environment_schedule(

 # [DEF:get_environment_databases:Function]
 # @PURPOSE: Fetch the list of databases from a specific environment.
+# @PRE:     Environment id exists.
+# @POST:    Returns a list of database summaries from the environment.
 # @PARAM:   id (str) - The environment ID.
 # @RETURN:  List[Dict] - List of databases.
@router.get("/{id}/databases")
 async def get_environment_databases(id: str, config_manager=Depends(get_config_manager)):
-    envs = config_manager.get_environments()
+    with belief_scope("get_environment_databases", f"id={id}"):
+        envs = config_manager.get_environments()
    env = next((e for e in envs if e.id == id), None)
    if not env:
        raise HTTPException(status_code=404, detail="Environment not found")
--- a/backend/src/api/routes/mappings.py
+++ b/backend/src/api/routes/mappings.py
@@ -53,13 +53,16 @@ class SuggestRequest(BaseModel):

 # [DEF:get_mappings:Function]
 # @PURPOSE: List all saved database mappings.
+# @PRE:     db session is injected.
+# @POST:    Returns filtered list of DatabaseMapping records.
@router.get("", response_model=List[MappingResponse])
 async def get_mappings(
    source_env_id: Optional[str] = None,
    target_env_id: Optional[str] = None,
    db: Session = Depends(get_db)
 ):
-    query = db.query(DatabaseMapping)
+    with belief_scope("get_mappings"):
+        query = db.query(DatabaseMapping)
    if source_env_id:
        query = query.filter(DatabaseMapping.source_env_id == source_env_id)
    if target_env_id:
@@ -69,42 +72,48 @@ async def get_mappings(

 # [DEF:create_mapping:Function]
 # @PURPOSE: Create or update a database mapping.
+# @PRE:     mapping is valid MappingCreate, db session is injected.
+# @POST:    DatabaseMapping created or updated in database.
@router.post("", response_model=MappingResponse)
 async def create_mapping(mapping: MappingCreate, db: Session = Depends(get_db)):
-    # Check if mapping already exists
-    existing = db.query(DatabaseMapping).filter(
-        DatabaseMapping.source_env_id == mapping.source_env_id,
-        DatabaseMapping.target_env_id == mapping.target_env_id,
-        DatabaseMapping.source_db_uuid == mapping.source_db_uuid
-    ).first()
-    
-    if existing:
-        existing.target_db_uuid = mapping.target_db_uuid
-        existing.target_db_name = mapping.target_db_name
+    with belief_scope("create_mapping"):
+        # Check if mapping already exists
+        existing = db.query(DatabaseMapping).filter(
+            DatabaseMapping.source_env_id == mapping.source_env_id,
+            DatabaseMapping.target_env_id == mapping.target_env_id,
+            DatabaseMapping.source_db_uuid == mapping.source_db_uuid
+        ).first()
+        
+        if existing:
+            existing.target_db_uuid = mapping.target_db_uuid
+            existing.target_db_name = mapping.target_db_name
+            db.commit()
+            db.refresh(existing)
+            return existing
+        
+        new_mapping = DatabaseMapping(**mapping.dict())
+        db.add(new_mapping)
        db.commit()
-        db.refresh(existing)
-        return existing
-    
-    new_mapping = DatabaseMapping(**mapping.dict())
-    db.add(new_mapping)
-    db.commit()
-    db.refresh(new_mapping)
-    return new_mapping
+        db.refresh(new_mapping)
+        return new_mapping
 # [/DEF:create_mapping:Function]

 # [DEF:suggest_mappings_api:Function]
 # @PURPOSE: Get suggested mappings based on fuzzy matching.
+# @PRE:     request is valid SuggestRequest, config_manager is injected.
+# @POST:    Returns mapping suggestions.
@router.post("/suggest")
 async def suggest_mappings_api(
    request: SuggestRequest,
    config_manager=Depends(get_config_manager)
 ):
-    from backend.src.services.mapping_service import MappingService
-    service = MappingService(config_manager)
-    try:
-        return await service.get_suggestions(request.source_env_id, request.target_env_id)
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))
+    with belief_scope("suggest_mappings_api"):
+        from backend.src.services.mapping_service import MappingService
+        service = MappingService(config_manager)
+        try:
+            return await service.get_suggestions(request.source_env_id, request.target_env_id)
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=str(e))
 # [/DEF:suggest_mappings_api:Function]

 # [/DEF:backend.src.api.routes.mappings:Module]
--- a/backend/src/api/routes/plugins.py
+++ b/backend/src/api/routes/plugins.py
@@ -11,12 +11,19 @@ from ...dependencies import get_plugin_loader

 router = APIRouter()

+# [DEF:list_plugins:Function]
+# @PURPOSE: Retrieve a list of all available plugins.
+# @PRE: plugin_loader is injected via Depends.
+# @POST: Returns a list of PluginConfig objects.
+# @RETURN: List[PluginConfig] - List of registered plugins.
@router.get("", response_model=List[PluginConfig])
 async def list_plugins(
    plugin_loader = Depends(get_plugin_loader)
 ):
-    """
-    Retrieve a list of all available plugins.
-    """
-    return plugin_loader.get_all_plugin_configs()
+    with belief_scope("list_plugins"):
+        """
+        Retrieve a list of all available plugins.
+        """
+        return plugin_loader.get_all_plugin_configs()
+# [/DEF:list_plugins:Function]
 # [/DEF:PluginsRouter:Module]
--- a/backend/src/api/routes/settings.py
+++ b/backend/src/api/routes/settings.py
@@ -15,7 +15,7 @@ from typing import List
 from ...core.config_models import AppConfig, Environment, GlobalSettings
 from ...dependencies import get_config_manager
 from ...core.config_manager import ConfigManager
-from ...core.logger import logger
+from ...core.logger import logger, belief_scope
 from ...core.superset_client import SupersetClient
 from superset_tool.models import SupersetConfig
 import os
@@ -25,10 +25,13 @@ router = APIRouter()

 # [DEF:get_settings:Function]
 # @PURPOSE: Retrieves all application settings.
+# @PRE:     Config manager is available.
+# @POST:    Returns masked AppConfig.
 # @RETURN: AppConfig - The current configuration.
@router.get("/", response_model=AppConfig)
 async def get_settings(config_manager: ConfigManager = Depends(get_config_manager)):
-    logger.info("[get_settings][Entry] Fetching all settings")
+    with belief_scope("get_settings"):
+        logger.info("[get_settings][Entry] Fetching all settings")
    config = config_manager.get_config().copy(deep=True)
    # Mask passwords
    for env in config.environments:
@@ -39,29 +42,37 @@ async def get_settings(config_manager: ConfigManager = Depends(get_config_manage

 # [DEF:update_global_settings:Function]
 # @PURPOSE: Updates global application settings.
+# @PRE:     New settings are provided.
+# @POST:    Global settings are updated.
 # @PARAM: settings (GlobalSettings) - The new global settings.
 # @RETURN: GlobalSettings - The updated settings.
@router.patch("/global", response_model=GlobalSettings)
 async def update_global_settings(
-    settings: GlobalSettings, 
+    settings: GlobalSettings,
    config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info("[update_global_settings][Entry] Updating global settings")
+    with belief_scope("update_global_settings"):
+        logger.info("[update_global_settings][Entry] Updating global settings")
    config_manager.update_global_settings(settings)
    return settings
 # [/DEF:update_global_settings:Function]

 # [DEF:get_environments:Function]
 # @PURPOSE: Lists all configured Superset environments.
+# @PRE:     Config manager is available.
+# @POST:    Returns list of environments.
 # @RETURN: List[Environment] - List of environments.
@router.get("/environments", response_model=List[Environment])
 async def get_environments(config_manager: ConfigManager = Depends(get_config_manager)):
-    logger.info("[get_environments][Entry] Fetching environments")
+    with belief_scope("get_environments"):
+        logger.info("[get_environments][Entry] Fetching environments")
    return config_manager.get_environments()
 # [/DEF:get_environments:Function]

 # [DEF:add_environment:Function]
 # @PURPOSE: Adds a new Superset environment.
+# @PRE:     Environment data is valid and reachable.
+# @POST:    Environment is added to config.
 # @PARAM: env (Environment) - The environment to add.
 # @RETURN: Environment - The added environment.
@router.post("/environments", response_model=Environment)
@@ -69,7 +80,8 @@ async def add_environment(
    env: Environment,
    config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[add_environment][Entry] Adding environment {env.id}")
+    with belief_scope("add_environment"):
+        logger.info(f"[add_environment][Entry] Adding environment {env.id}")
    
    # Validate connection before adding
    try:
@@ -95,16 +107,19 @@ async def add_environment(

 # [DEF:update_environment:Function]
 # @PURPOSE: Updates an existing Superset environment.
+# @PRE:     ID and valid environment data are provided.
+# @POST:    Environment is updated in config.
 # @PARAM: id (str) - The ID of the environment to update.
 # @PARAM: env (Environment) - The updated environment data.
 # @RETURN: Environment - The updated environment.
@router.put("/environments/{id}", response_model=Environment)
 async def update_environment(
-    id: str, 
-    env: Environment, 
+    id: str,
+    env: Environment,
    config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[update_environment][Entry] Updating environment {id}")
+    with belief_scope("update_environment"):
+        logger.info(f"[update_environment][Entry] Updating environment {id}")
    
    # If password is masked, we need the real one for validation
    env_to_validate = env.copy(deep=True)
@@ -138,19 +153,24 @@ async def update_environment(

 # [DEF:delete_environment:Function]
 # @PURPOSE: Deletes a Superset environment.
+# @PRE:     ID is provided.
+# @POST:    Environment is removed from config.
 # @PARAM: id (str) - The ID of the environment to delete.
@router.delete("/environments/{id}")
 async def delete_environment(
-    id: str, 
+    id: str,
    config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[delete_environment][Entry] Deleting environment {id}")
+    with belief_scope("delete_environment"):
+        logger.info(f"[delete_environment][Entry] Deleting environment {id}")
    config_manager.delete_environment(id)
    return {"message": f"Environment {id} deleted"}
 # [/DEF:delete_environment:Function]

 # [DEF:test_environment_connection:Function]
 # @PURPOSE: Tests the connection to a Superset environment.
+# @PRE:     ID is provided.
+# @POST:    Returns success or error status.
 # @PARAM: id (str) - The ID of the environment to test.
 # @RETURN: dict - Success message or error.
@router.post("/environments/{id}/test")
@@ -158,7 +178,8 @@ async def test_environment_connection(
    id: str,
    config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    logger.info(f"[test_environment_connection][Entry] Testing environment {id}")
+    with belief_scope("test_environment_connection"):
+        logger.info(f"[test_environment_connection][Entry] Testing environment {id}")
    
    # Find environment
    env = next((e for e in config_manager.get_environments() if e.id == id), None)
@@ -194,6 +215,8 @@ async def test_environment_connection(

 # [DEF:validate_backup_path:Function]
 # @PURPOSE: Validates if a backup path exists and is writable.
+# @PRE:     Path is provided in path_data.
+# @POST:    Returns success or error status.
 # @PARAM: path (str) - The path to validate.
 # @RETURN: dict - Validation result.
@router.post("/validate-path")
@@ -201,11 +224,12 @@ async def validate_backup_path(
    path_data: dict,
    config_manager: ConfigManager = Depends(get_config_manager)
 ):
-    path = path_data.get("path")
-    if not path:
-        raise HTTPException(status_code=400, detail="Path is required")
-    
-    logger.info(f"[validate_backup_path][Entry] Validating path: {path}")
+    with belief_scope("validate_backup_path"):
+        path = path_data.get("path")
+        if not path:
+            raise HTTPException(status_code=400, detail="Path is required")
+        
+        logger.info(f"[validate_backup_path][Entry] Validating path: {path}")
    
    valid, message = config_manager.validate_path(path)
    
--- a/backend/src/api/routes/tasks.py
+++ b/backend/src/api/routes/tasks.py
@@ -6,6 +6,7 @@
 from typing import List, Dict, Any, Optional
 from fastapi import APIRouter, Depends, HTTPException, status
 from pydantic import BaseModel
+from ...core.logger import belief_scope

 from ...core.task_manager import TaskManager, Task, TaskStatus, LogEntry
 from ...dependencies import get_task_manager
@@ -23,6 +24,13 @@ class ResumeTaskRequest(BaseModel):
    passwords: Dict[str, str]

@router.post("", response_model=Task, status_code=status.HTTP_201_CREATED)
+# [DEF:create_task:Function]
+# @PURPOSE: Create and start a new task for a given plugin.
+# @PARAM: request (CreateTaskRequest) - The request body containing plugin_id and params.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: plugin_id must exist and params must be valid for that plugin.
+# @POST: A new task is created and started.
+# @RETURN: Task - The created task instance.
 async def create_task(
    request: CreateTaskRequest,
    task_manager: TaskManager = Depends(get_task_manager)
@@ -30,16 +38,27 @@ async def create_task(
    """
    Create and start a new task for a given plugin.
    """
-    try:
-        task = await task_manager.create_task(
-            plugin_id=request.plugin_id,
-            params=request.params
-        )
-        return task
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+    with belief_scope("create_task"):
+        try:
+            task = await task_manager.create_task(
+                plugin_id=request.plugin_id,
+                params=request.params
+            )
+            return task
+        except ValueError as e:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(e))
+# [/DEF:create_task:Function]

@router.get("", response_model=List[Task])
+# [DEF:list_tasks:Function]
+# @PURPOSE: Retrieve a list of tasks with pagination and optional status filter.
+# @PARAM: limit (int) - Maximum number of tasks to return.
+# @PARAM: offset (int) - Number of tasks to skip.
+# @PARAM: status (Optional[TaskStatus]) - Filter by task status.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task_manager must be available.
+# @POST: Returns a list of tasks.
+# @RETURN: List[Task] - List of tasks.
 async def list_tasks(
    limit: int = 10,
    offset: int = 0,
@@ -49,9 +68,18 @@ async def list_tasks(
    """
    Retrieve a list of tasks with pagination and optional status filter.
    """
-    return task_manager.get_tasks(limit=limit, offset=offset, status=status)
+    with belief_scope("list_tasks"):
+        return task_manager.get_tasks(limit=limit, offset=offset, status=status)
+# [/DEF:list_tasks:Function]

@router.get("/{task_id}", response_model=Task)
+# [DEF:get_task:Function]
+# @PURPOSE: Retrieve the details of a specific task.
+# @PARAM: task_id (str) - The unique identifier of the task.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task_id must exist.
+# @POST: Returns task details or raises 404.
+# @RETURN: Task - The task details.
 async def get_task(
    task_id: str,
    task_manager: TaskManager = Depends(get_task_manager)
@@ -59,12 +87,21 @@ async def get_task(
    """
    Retrieve the details of a specific task.
    """
-    task = task_manager.get_task(task_id)
-    if not task:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
-    return task
+    with belief_scope("get_task"):
+        task = task_manager.get_task(task_id)
+        if not task:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
+        return task
+# [/DEF:get_task:Function]

@router.get("/{task_id}/logs", response_model=List[LogEntry])
+# [DEF:get_task_logs:Function]
+# @PURPOSE: Retrieve logs for a specific task.
+# @PARAM: task_id (str) - The unique identifier of the task.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task_id must exist.
+# @POST: Returns a list of log entries or raises 404.
+# @RETURN: List[LogEntry] - List of log entries.
 async def get_task_logs(
    task_id: str,
    task_manager: TaskManager = Depends(get_task_manager)
@@ -72,12 +109,22 @@ async def get_task_logs(
    """
    Retrieve logs for a specific task.
    """
-    task = task_manager.get_task(task_id)
-    if not task:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
-    return task_manager.get_task_logs(task_id)
+    with belief_scope("get_task_logs"):
+        task = task_manager.get_task(task_id)
+        if not task:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Task not found")
+        return task_manager.get_task_logs(task_id)
+# [/DEF:get_task_logs:Function]

@router.post("/{task_id}/resolve", response_model=Task)
+# [DEF:resolve_task:Function]
+# @PURPOSE: Resolve a task that is awaiting mapping.
+# @PARAM: task_id (str) - The unique identifier of the task.
+# @PARAM: request (ResolveTaskRequest) - The resolution parameters.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task must be in AWAITING_MAPPING status.
+# @POST: Task is resolved and resumes execution.
+# @RETURN: Task - The updated task object.
 async def resolve_task(
    task_id: str,
    request: ResolveTaskRequest,
@@ -86,13 +133,23 @@ async def resolve_task(
    """
    Resolve a task that is awaiting mapping.
    """
-    try:
-        await task_manager.resolve_task(task_id, request.resolution_params)
-        return task_manager.get_task(task_id)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    with belief_scope("resolve_task"):
+        try:
+            await task_manager.resolve_task(task_id, request.resolution_params)
+            return task_manager.get_task(task_id)
+        except ValueError as e:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+# [/DEF:resolve_task:Function]

@router.post("/{task_id}/resume", response_model=Task)
+# [DEF:resume_task:Function]
+# @PURPOSE: Resume a task that is awaiting input (e.g., passwords).
+# @PARAM: task_id (str) - The unique identifier of the task.
+# @PARAM: request (ResumeTaskRequest) - The input (passwords).
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task must be in AWAITING_INPUT status.
+# @POST: Task resumes execution with provided input.
+# @RETURN: Task - The updated task object.
 async def resume_task(
    task_id: str,
    request: ResumeTaskRequest,
@@ -101,13 +158,21 @@ async def resume_task(
    """
    Resume a task that is awaiting input (e.g., passwords).
    """
-    try:
-        task_manager.resume_task_with_password(task_id, request.passwords)
-        return task_manager.get_task(task_id)
-    except ValueError as e:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+    with belief_scope("resume_task"):
+        try:
+            task_manager.resume_task_with_password(task_id, request.passwords)
+            return task_manager.get_task(task_id)
+        except ValueError as e:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+# [/DEF:resume_task:Function]

@router.delete("", status_code=status.HTTP_204_NO_CONTENT)
+# [DEF:clear_tasks:Function]
+# @PURPOSE: Clear tasks matching the status filter.
+# @PARAM: status (Optional[TaskStatus]) - Filter by task status.
+# @PARAM: task_manager (TaskManager) - The task manager instance.
+# @PRE: task_manager is available.
+# @POST: Tasks are removed from memory/persistence.
 async def clear_tasks(
    status: Optional[TaskStatus] = None,
    task_manager: TaskManager = Depends(get_task_manager)
@@ -115,6 +180,8 @@ async def clear_tasks(
    """
    Clear tasks matching the status filter. If no filter, clears all non-running tasks.
    """
-    task_manager.clear_tasks(status)
-    return
+    with belief_scope("clear_tasks", f"status={status}"):
+        task_manager.clear_tasks(status)
+        return
+# [/DEF:clear_tasks:Function]
 # [/DEF:TasksRouter:Module]