semantic cleanup

backend/src/api/routes/git.py

@@ -30,6 +30,8 @@ git_service = GitService()
 
 # [DEF:get_git_configs:Function]
 # @PURPOSE: List all configured Git servers.
+# @PRE: Database session `db` is available.
+# @POST: Returns a list of all GitServerConfig objects from the database.
 # @RETURN: List[GitServerConfigSchema]
 @router.get("/config", response_model=List[GitServerConfigSchema])
 async def get_git_configs(db: Session = Depends(get_db)):
@@ -39,6 +41,8 @@ async def get_git_configs(db: Session = Depends(get_db)):
 
 # [DEF:create_git_config:Function]
 # @PURPOSE: Register a new Git server configuration.
+# @PRE: `config` contains valid GitServerConfigCreate data.
+# @POST: A new GitServerConfig record is created in the database.
 # @PARAM: config (GitServerConfigCreate)
 # @RETURN: GitServerConfigSchema
 @router.post("/config", response_model=GitServerConfigSchema)
@@ -53,6 +57,8 @@ async def create_git_config(config: GitServerConfigCreate, db: Session = Depends
 
 # [DEF:delete_git_config:Function]
 # @PURPOSE: Remove a Git server configuration.
+# @PRE: `config_id` corresponds to an existing configuration.
+# @POST: The configuration record is removed from the database.
 # @PARAM: config_id (str)
 @router.delete("/config/{config_id}")
 async def delete_git_config(config_id: str, db: Session = Depends(get_db)):
@@ -68,6 +74,8 @@ async def delete_git_config(config_id: str, db: Session = Depends(get_db)):
 
 # [DEF:test_git_config:Function]
 # @PURPOSE: Validate connection to a Git server using provided credentials.
+# @PRE: `config` contains provider, url, and pat.
+# @POST: Returns success if the connection is validated via GitService.
 # @PARAM: config (GitServerConfigCreate)
 @router.post("/config/test")
 async def test_git_config(config: GitServerConfigCreate):
@@ -81,6 +89,8 @@ async def test_git_config(config: GitServerConfigCreate):
 
 # [DEF:init_repository:Function]
 # @PURPOSE: Link a dashboard to a Git repository and perform initial clone/init.
+# @PRE: `dashboard_id` exists and `init_data` contains valid config_id and remote_url.
+# @POST: Repository is initialized on disk and a GitRepository record is saved in DB.
 # @PARAM: dashboard_id (int)
 # @PARAM: init_data (RepoInitRequest)
 @router.post("/repositories/{dashboard_id}/init")
@@ -123,6 +133,8 @@ async def init_repository(dashboard_id: int, init_data: RepoInitRequest, db: Ses
 
 # [DEF:get_branches:Function]
 # @PURPOSE: List all branches for a dashboard's repository.
+# @PRE: Repository for `dashboard_id` is initialized.
+# @POST: Returns a list of branches from the local repository.
 # @PARAM: dashboard_id (int)
 # @RETURN: List[BranchSchema]
 @router.get("/repositories/{dashboard_id}/branches", response_model=List[BranchSchema])
@@ -136,6 +148,8 @@ async def get_branches(dashboard_id: int):
 
 # [DEF:create_branch:Function]
 # @PURPOSE: Create a new branch in the dashboard's repository.
+# @PRE: `dashboard_id` repository exists and `branch_data` has name and from_branch.
+# @POST: A new branch is created in the local repository.
 # @PARAM: dashboard_id (int)
 # @PARAM: branch_data (BranchCreate)
 @router.post("/repositories/{dashboard_id}/branches")
@@ -150,6 +164,8 @@ async def create_branch(dashboard_id: int, branch_data: BranchCreate):
 
 # [DEF:checkout_branch:Function]
 # @PURPOSE: Switch the dashboard's repository to a specific branch.
+# @PRE: `dashboard_id` repository exists and branch `checkout_data.name` exists.
+# @POST: The local repository HEAD is moved to the specified branch.
 # @PARAM: dashboard_id (int)
 # @PARAM: checkout_data (BranchCheckout)
 @router.post("/repositories/{dashboard_id}/checkout")
@@ -164,6 +180,8 @@ async def checkout_branch(dashboard_id: int, checkout_data: BranchCheckout):
 
 # [DEF:commit_changes:Function]
 # @PURPOSE: Stage and commit changes in the dashboard's repository.
+# @PRE: `dashboard_id` repository exists and `commit_data` has message and files.
+# @POST: Specified files are staged and a new commit is created.
 # @PARAM: dashboard_id (int)
 # @PARAM: commit_data (CommitCreate)
 @router.post("/repositories/{dashboard_id}/commit")
@@ -178,6 +196,8 @@ async def commit_changes(dashboard_id: int, commit_data: CommitCreate):
 
 # [DEF:push_changes:Function]
 # @PURPOSE: Push local commits to the remote repository.
+# @PRE: `dashboard_id` repository exists and has a remote configured.
+# @POST: Local commits are pushed to the remote repository.
 # @PARAM: dashboard_id (int)
 @router.post("/repositories/{dashboard_id}/push")
 async def push_changes(dashboard_id: int):
@@ -191,6 +211,8 @@ async def push_changes(dashboard_id: int):
 
 # [DEF:pull_changes:Function]
 # @PURPOSE: Pull changes from the remote repository.
+# @PRE: `dashboard_id` repository exists and has a remote configured.
+# @POST: Remote changes are fetched and merged into the local branch.
 # @PARAM: dashboard_id (int)
 @router.post("/repositories/{dashboard_id}/pull")
 async def pull_changes(dashboard_id: int):
@@ -204,6 +226,8 @@ async def pull_changes(dashboard_id: int):
 
 # [DEF:sync_dashboard:Function]
 # @PURPOSE: Sync dashboard state from Superset to Git using the GitPlugin.
+# @PRE: `dashboard_id` is valid; GitPlugin is available.
+# @POST: Dashboard YAMLs are exported from Superset and committed to Git.
 # @PARAM: dashboard_id (int)
 # @PARAM: source_env_id (Optional[str])
 @router.post("/repositories/{dashboard_id}/sync")
@@ -223,6 +247,8 @@ async def sync_dashboard(dashboard_id: int, source_env_id: typing.Optional[str]
 
 # [DEF:get_environments:Function]
 # @PURPOSE: List all deployment environments.
+# @PRE: Config manager is accessible.
+# @POST: Returns a list of DeploymentEnvironmentSchema objects.
 # @RETURN: List[DeploymentEnvironmentSchema]
 @router.get("/environments", response_model=List[DeploymentEnvironmentSchema])
 async def get_environments(config_manager=Depends(get_config_manager)):
@@ -240,6 +266,8 @@ async def get_environments(config_manager=Depends(get_config_manager)):
 
 # [DEF:deploy_dashboard:Function]
 # @PURPOSE: Deploy dashboard from Git to a target environment.
+# @PRE: `dashboard_id` and `deploy_data.environment_id` are valid.
+# @POST: Dashboard YAMLs are read from Git and imported into the target Superset.
 # @PARAM: dashboard_id (int)
 # @PARAM: deploy_data (DeployRequest)
 @router.post("/repositories/{dashboard_id}/deploy")
@@ -259,6 +287,8 @@ async def deploy_dashboard(dashboard_id: int, deploy_data: DeployRequest):
 
 # [DEF:get_history:Function]
 # @PURPOSE: View commit history for a dashboard's repository.
+# @PRE: `dashboard_id` repository exists.
+# @POST: Returns a list of recent commits from the repository.
 # @PARAM: dashboard_id (int)
 # @PARAM: limit (int)
 # @RETURN: List[CommitSchema]
@@ -273,6 +303,8 @@ async def get_history(dashboard_id: int, limit: int = 50):
 
 # [DEF:get_repository_status:Function]
 # @PURPOSE: Get current Git status for a dashboard repository.
+# @PRE: `dashboard_id` repository exists.
+# @POST: Returns the status of the working directory (staged, unstaged, untracked).
 # @PARAM: dashboard_id (int)
 # @RETURN: dict
 @router.get("/repositories/{dashboard_id}/status")
@@ -286,6 +318,8 @@ async def get_repository_status(dashboard_id: int):
 
 # [DEF:get_repository_diff:Function]
 # @PURPOSE: Get Git diff for a dashboard repository.
+# @PRE: `dashboard_id` repository exists.
+# @POST: Returns the diff text for the specified file or all changes.
 # @PARAM: dashboard_id (int)
 # @PARAM: file_path (Optional[str])
 # @PARAM: staged (bool)