chore(semantics): checkpoint orphan-reduction hub normalization batch

backend/src/services/git_service.py

@@ -4,12 +4,11 @@
 # @SEMANTICS: git, service, gitpython, repository, version_control
 # @PURPOSE:   Core Git logic using GitPython to manage dashboard repositories.
 # @LAYER:     Service
-# @RELATION:  INHERITS_FROM -> None
-# @RELATION:  USED_BY -> src.api.routes.git
-# @RELATION:  USED_BY -> src.plugins.git_plugin
-# @RELATION:  DEPENDS_ON -> src.core.database.SessionLocal
-# @RELATION:  DEPENDS_ON -> src.models.config.AppConfigRecord
-# @RELATION:  DEPENDS_ON -> src.models.git.GitRepository
+# @RELATION:  USED_BY -> backend.src.api.routes.git
+# @RELATION:  USED_BY -> backend.src.plugins.git_plugin
+# @RELATION:  DEPENDS_ON -> backend.src.core.database.SessionLocal
+# @RELATION:  DEPENDS_ON -> backend.src.models.config.AppConfigRecord
+# @RELATION:  DEPENDS_ON -> backend.src.models.git.GitRepository
 #
 # @INVARIANT: All Git operations must be performed on a valid local directory.
 
@@ -32,14 +31,15 @@ from src.models.git import GitRepository, GitServerConfig
 from src.models.config import AppConfigRecord
 from src.core.database import SessionLocal
 
-# [DEF:GitService:Class]
+# [DEF:backend.src.services.git_service.GitService:Class]
+# @TIER: STANDARD
 # @PURPOSE: Wrapper for GitPython operations with semantic logging and error handling.
 class GitService:
     """
     Wrapper for GitPython operations.
     """
 
-    # [DEF:__init__:Function]
+    # [DEF:backend.src.services.git_service.GitService.__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.
@@ -64,7 +64,7 @@ class GitService:
         base.mkdir(parents=True, exist_ok=True)
     # [/DEF:_ensure_base_path_exists:Function]
 
-    # [DEF:_resolve_base_path:Function]
+    # [DEF:backend.src.services.git_service.GitService._resolve_base_path:Function]
     # @PURPOSE: Resolve base repository directory from explicit argument or global storage settings.
     # @PRE: base_path is a string path.
     # @POST: Returns absolute path for Git repositories root.
@@ -254,7 +254,7 @@ class GitService:
                 )
     # [/DEF:_ensure_gitflow_branches:Function]
 
-    # [DEF:_get_repo_path:Function]
+    # [DEF:backend.src.services.git_service.GitService._get_repo_path:Function]
     # @PURPOSE: Resolves the local filesystem path for a dashboard's repository.
     # @PARAM: dashboard_id (int)
     # @PARAM: repo_key (Optional[str]) - Slug-like key used when DB local_path is absent.
@@ -394,7 +394,7 @@ class GitService:
                 session.close()
     # [/DEF:delete_repo:Function]
 
-    # [DEF:get_repo:Function]
+    # [DEF:backend.src.services.git_service.GitService.get_repo:Function]
     # @PURPOSE: Get Repo object for a dashboard.
     # @PRE: Repository must exist on disk for the given dashboard_id.
     # @POST: Returns a GitPython Repo instance for the dashboard.
@@ -1112,7 +1112,7 @@ class GitService:
                 raise HTTPException(status_code=500, detail=f"Git pull failed: {str(e)}")
     # [/DEF:pull_changes:Function]
 
-    # [DEF:get_status:Function]
+    # [DEF:backend.src.services.git_service.GitService.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.
@@ -1657,7 +1657,7 @@ class GitService:
         }
     # [/DEF:_parse_remote_repo_identity:Function]
 
-    # [DEF:_derive_server_url_from_remote:Function]
+    # [DEF:backend.src.services.git_service.GitService._derive_server_url_from_remote:Function]
     # @PURPOSE: Build API base URL from remote repository URL without credentials.
     # @PRE: remote_url may be any git URL.
     # @POST: Returns normalized http(s) base URL or None when derivation is impossible.
@@ -1744,7 +1744,7 @@ class GitService:
             }
     # [/DEF:promote_direct_merge:Function]
 
-    # [DEF:create_gitea_pull_request:Function]
+    # [DEF:backend.src.services.git_service.GitService.create_gitea_pull_request:Function]
     # @PURPOSE: Create pull request in Gitea.
     # @PRE: Config and remote URL are valid.
     # @POST: Returns normalized PR metadata.
@@ -1832,7 +1832,7 @@ class GitService:
         }
     # [/DEF:create_gitea_pull_request:Function]
 
-    # [DEF:create_github_pull_request:Function]
+    # [DEF:backend.src.services.git_service.GitService.create_github_pull_request:Function]
     # @PURPOSE: Create pull request in GitHub or GitHub Enterprise.
     # @PRE: Config and remote URL are valid.
     # @POST: Returns normalized PR metadata.
@@ -1886,7 +1886,7 @@ class GitService:
         }
     # [/DEF:create_github_pull_request:Function]
 
-    # [DEF:create_gitlab_merge_request:Function]
+    # [DEF:backend.src.services.git_service.GitService.create_gitlab_merge_request:Function]
     # @PURPOSE: Create merge request in GitLab.
     # @PRE: Config and remote URL are valid.
     # @POST: Returns normalized MR metadata.