semantics

backend/src/services/git/_base.py

@@ -1,4 +1,4 @@
-# #region GitServiceBase [C:3] [TYPE Module] [SEMANTICS git, service, repository, version_control, initialization]
+# #region GitServiceBase [C:3] [TYPE Module] [SEMANTICS git, repository, clone, base, mixin]
 # @LAYER: Infra
 # @BRIEF Core GitService base class — initialization, path resolution, repo lifecycle (init/delete/get), and identity configuration.
 # @RELATION INHERITED_BY -> [GitService]
@@ -23,7 +23,7 @@ from src.core.database import SessionLocal
 # #region GitServiceBase [C:3] [TYPE Class]
 # @BRIEF Base class for GitService providing initialization, path resolution, repository lifecycle, and identity.
 class GitServiceBase:
-    # [DEF:GitService_init:Function]
+    # region GitService_init [TYPE 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.
@@ -35,9 +35,9 @@ class GitServiceBase:
             self._uses_default_base_path = base_path == "git_repos"
             self.base_path = self._resolve_base_path(base_path)
             self._ensure_base_path_exists()
-    # [/DEF:GitService_init:Function]
+    # endregion GitService_init
 
-    # [DEF:_ensure_base_path_exists:Function]
+    # region _ensure_base_path_exists [TYPE Function]
     # @PURPOSE: Ensure the repositories root directory exists and is a directory.
     # @PRE: self.base_path is resolved to filesystem path.
     # @POST: self.base_path exists as directory or raises ValueError.
@@ -52,9 +52,9 @@ class GitServiceBase:
                 f"[_ensure_base_path_exists][Coherence:Failed] Cannot create Git repositories base path: {self.base_path}. Error: {e}"
             )
             raise ValueError(f"Cannot create Git repositories base path: {self.base_path}. {e}")
-    # [/DEF:_ensure_base_path_exists:Function]
+    # endregion _ensure_base_path_exists
 
-    # [DEF:_resolve_base_path:Function]
+    # region _resolve_base_path [TYPE 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.
@@ -87,9 +87,9 @@ class GitServiceBase:
         except Exception as e:
             logger.warning(f"[_resolve_base_path][Coherence:Failed] Falling back to default path: {e}")
             return fallback_path
-    # [/DEF:_resolve_base_path:Function]
+    # endregion _resolve_base_path
 
-    # [DEF:_normalize_repo_key:Function]
+    # region _normalize_repo_key [TYPE Function]
     # @PURPOSE: Convert user/dashboard-provided key to safe filesystem directory name.
     # @PRE: repo_key can be None/empty.
     # @POST: Returns normalized non-empty key.
@@ -98,9 +98,9 @@ class GitServiceBase:
         raw_key = str(repo_key or "").strip().lower()
         normalized = re.sub(r"[^a-z0-9._-]+", "-", raw_key).strip("._-")
         return normalized or "dashboard"
-    # [/DEF:_normalize_repo_key:Function]
+    # endregion _normalize_repo_key
 
-    # [DEF:_update_repo_local_path:Function]
+    # region _update_repo_local_path [TYPE Function]
     # @PURPOSE: Persist repository local_path in GitRepository table when record exists.
     # @PRE: dashboard_id is valid integer.
     # @POST: local_path is updated for existing record.
@@ -120,9 +120,9 @@ class GitServiceBase:
                 session.close()
         except Exception as e:
             logger.warning(f"[_update_repo_local_path][Coherence:Failed] {e}")
-    # [/DEF:_update_repo_local_path:Function]
+    # endregion _update_repo_local_path
 
-    # [DEF:_migrate_repo_directory:Function]
+    # region _migrate_repo_directory [TYPE Function]
     # @PURPOSE: Move legacy repository directory to target path and sync DB metadata.
     # @PRE: source_path exists.
     # @POST: Repository content available at target_path.
@@ -145,9 +145,9 @@ class GitServiceBase:
             f"[_migrate_repo_directory][Coherence:OK] Repository migrated for dashboard {dashboard_id}: {source_abs} -> {target_abs}"
         )
         return target_abs
-    # [/DEF:_migrate_repo_directory:Function]
+    # endregion _migrate_repo_directory
 
-    # [DEF:_get_repo_path:Function]
+    # region _get_repo_path [TYPE 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.
@@ -191,9 +191,9 @@ class GitServiceBase:
             if os.path.exists(target_path):
                 self._update_repo_local_path(dashboard_id, target_path)
             return target_path
-    # [/DEF:_get_repo_path:Function]
+    # endregion _get_repo_path
 
-    # [DEF:init_repo:Function]
+    # region init_repo [TYPE Function]
     # @PURPOSE: Initialize or clone a repository for a dashboard.
     # @PARAM: dashboard_id (int), remote_url (str), pat (str), repo_key (Optional[str]).
     # @PRE: dashboard_id is int, remote_url is valid Git URL, pat is provided.
@@ -230,9 +230,9 @@ class GitServiceBase:
             repo = Repo.clone_from(auth_url, repo_path)
             self._ensure_gitflow_branches(repo, dashboard_id)
             return repo
-    # [/DEF:init_repo:Function]
+    # endregion init_repo
 
-    # [DEF:delete_repo:Function]
+    # region delete_repo [TYPE Function]
     # @PURPOSE: Remove local repository and DB binding for a dashboard.
     # @PRE: dashboard_id is a valid integer.
     # @POST: Local path is deleted when present and GitRepository row is removed.
@@ -272,9 +272,9 @@ class GitServiceBase:
                 raise HTTPException(status_code=500, detail=f"Failed to delete repository: {str(e)}")
             finally:
                 session.close()
-    # [/DEF:delete_repo:Function]
+    # endregion delete_repo
 
-    # [DEF:get_repo:Function]
+    # region get_repo [TYPE 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.
@@ -290,9 +290,9 @@ class GitServiceBase:
             except Exception as e:
                 logger.error(f"[get_repo][Coherence:Failed] Failed to open repository at {repo_path}: {e}")
                 raise HTTPException(status_code=500, detail="Failed to open local Git repository")
-    # [/DEF:get_repo:Function]
+    # endregion get_repo
 
-    # [DEF:configure_identity:Function]
+    # region configure_identity [TYPE Function]
     # @PURPOSE: Configure repository-local Git committer identity for user-scoped operations.
     # @PRE: dashboard_id repository exists; git_username/git_email may be empty.
     # @POST: Repository config has user.name and user.email when both identity values are provided.
@@ -311,6 +311,6 @@ class GitServiceBase:
             except Exception as e:
                 logger.error(f"[configure_identity][Coherence:Failed] Failed to configure git identity: {e}")
                 raise HTTPException(status_code=500, detail=f"Failed to configure git identity: {str(e)}")
-    # [/DEF:configure_identity:Function]
+    # endregion configure_identity
 # #endregion GitServiceBase
 # #endregion GitServiceBase