semantic cleanup

backend/src/services/git_service.py

@@ -29,6 +29,8 @@ class GitService:
     # [DEF:__init__:Function]
     # @PURPOSE: Initializes the GitService with a base path for repositories.
     # @PARAM: base_path (str) - Root directory for all Git clones.
+    # @PRE: base_path is a valid string path.
+    # @POST: GitService is initialized; base_path directory exists.
     def __init__(self, base_path: str = "backend/git_repos"):
         with belief_scope("GitService.__init__"):
             self.base_path = base_path
@@ -39,9 +41,12 @@ class GitService:
     # [DEF:_get_repo_path:Function]
     # @PURPOSE: Resolves the local filesystem path for a dashboard's repository.
     # @PARAM: dashboard_id (int)
+    # @PRE: dashboard_id is an integer.
+    # @POST: Returns the absolute or relative path to the dashboard's repo.
     # @RETURN: str
     def _get_repo_path(self, dashboard_id: int) -> str:
-        return os.path.join(self.base_path, str(dashboard_id))
+        with belief_scope("GitService._get_repo_path"):
+            return os.path.join(self.base_path, str(dashboard_id))
     # [/DEF:_get_repo_path:Function]
 
     # [DEF:init_repo:Function]
@@ -49,6 +54,8 @@ class GitService:
     # @PARAM: dashboard_id (int)
     # @PARAM: remote_url (str)
     # @PARAM: pat (str) - Personal Access Token for authentication.
+    # @PRE: dashboard_id is int, remote_url is valid Git URL, pat is provided.
+    # @POST: Repository is cloned or opened at the local path.
     # @RETURN: Repo - GitPython Repo object.
     def init_repo(self, dashboard_id: int, remote_url: str, pat: str) -> Repo:
         with belief_scope("GitService.init_repo"):
@@ -71,7 +78,8 @@ class GitService:
 
     # [DEF:get_repo:Function]
     # @PURPOSE: Get Repo object for a dashboard.
-    # @PRE: Repository must exist on disk.
+    # @PRE: Repository must exist on disk for the given dashboard_id.
+    # @POST: Returns a GitPython Repo instance for the dashboard.
     # @RETURN: Repo
     def get_repo(self, dashboard_id: int) -> Repo:
         with belief_scope("GitService.get_repo"):
@@ -88,6 +96,8 @@ class GitService:
 
     # [DEF:list_branches:Function]
     # @PURPOSE: List all branches for a dashboard's repository.
+    # @PRE: Repository for dashboard_id exists.
+    # @POST: Returns a list of branch metadata dictionaries.
     # @RETURN: List[dict]
     def list_branches(self, dashboard_id: int) -> List[dict]:
         with belief_scope("GitService.list_branches"):
@@ -142,6 +152,8 @@ class GitService:
     # @PURPOSE: Create a new branch from an existing one.
     # @PARAM: name (str) - New branch name.
     # @PARAM: from_branch (str) - Source branch.
+    # @PRE: Repository exists; name is valid; from_branch exists or repo is empty.
+    # @POST: A new branch is created in the repository.
     def create_branch(self, dashboard_id: int, name: str, from_branch: str = "main"):
         with belief_scope("GitService.create_branch"):
             repo = self.get_repo(dashboard_id)
@@ -171,10 +183,11 @@ class GitService:
                 logger.error(f"[create_branch][Coherence:Failed] {e}")
                 raise
     # [/DEF:create_branch:Function]
-    # [/DEF:create_branch:Function]
 
     # [DEF:checkout_branch:Function]
     # @PURPOSE: Switch to a specific branch.
+    # @PRE: Repository exists and the specified branch name exists.
+    # @POST: The repository working directory is updated to the specified branch.
     def checkout_branch(self, dashboard_id: int, name: str):
         with belief_scope("GitService.checkout_branch"):
             repo = self.get_repo(dashboard_id)
@@ -186,6 +199,8 @@ class GitService:
     # @PURPOSE: Stage and commit changes.
     # @PARAM: message (str) - Commit message.
     # @PARAM: files (List[str]) - Optional list of specific files to stage.
+    # @PRE: Repository exists and has changes (dirty) or files are specified.
+    # @POST: Changes are staged and a new commit is created.
     def commit_changes(self, dashboard_id: int, message: str, files: List[str] = None):
         with belief_scope("GitService.commit_changes"):
             repo = self.get_repo(dashboard_id)
@@ -208,6 +223,8 @@ class GitService:
 
     # [DEF:push_changes:Function]
     # @PURPOSE: Push local commits to remote.
+    # @PRE: Repository exists and has an 'origin' remote.
+    # @POST: Local branch commits are pushed to origin.
     def push_changes(self, dashboard_id: int):
         with belief_scope("GitService.push_changes"):
             repo = self.get_repo(dashboard_id)
@@ -240,6 +257,8 @@ class GitService:
 
     # [DEF:pull_changes:Function]
     # @PURPOSE: Pull changes from remote.
+    # @PRE: Repository exists and has an 'origin' remote.
+    # @POST: Changes from origin are pulled and merged into the active branch.
     def pull_changes(self, dashboard_id: int):
         with belief_scope("GitService.pull_changes"):
             repo = self.get_repo(dashboard_id)
@@ -261,6 +280,8 @@ class GitService:
 
     # [DEF:get_status:Function]
     # @PURPOSE: Get current repository status (dirty files, untracked, etc.)
+    # @PRE: Repository for dashboard_id exists.
+    # @POST: Returns a dictionary representing the Git status.
     # @RETURN: dict
     def get_status(self, dashboard_id: int) -> dict:
         with belief_scope("GitService.get_status"):
@@ -287,6 +308,8 @@ class GitService:
     # @PURPOSE: Generate diff for a file or the whole repository.
     # @PARAM: file_path (str) - Optional specific file.
     # @PARAM: staged (bool) - Whether to show staged changes.
+    # @PRE: Repository for dashboard_id exists.
+    # @POST: Returns the diff text as a string.
     # @RETURN: str
     def get_diff(self, dashboard_id: int, file_path: str = None, staged: bool = False) -> str:
         with belief_scope("GitService.get_diff"):
@@ -303,6 +326,8 @@ class GitService:
     # [DEF:get_commit_history:Function]
     # @PURPOSE: Retrieve commit history for a repository.
     # @PARAM: limit (int) - Max number of commits to return.
+    # @PRE: Repository for dashboard_id exists.
+    # @POST: Returns a list of dictionaries for each commit in history.
     # @RETURN: List[dict]
     def get_commit_history(self, dashboard_id: int, limit: int = 50) -> List[dict]:
         with belief_scope("GitService.get_commit_history"):
@@ -333,6 +358,8 @@ class GitService:
     # @PARAM: provider (GitProvider)
     # @PARAM: url (str)
     # @PARAM: pat (str)
+    # @PRE: provider is valid; url is a valid HTTP(S) URL; pat is provided.
+    # @POST: Returns True if connection to the provider's API succeeds.
     # @RETURN: bool
     async def test_connection(self, provider: GitProvider, url: str, pat: str) -> bool:
         with belief_scope("GitService.test_connection"):