semantics

backend/src/services/git/_status.py

@@ -1,7 +1,7 @@
 # #region GitServiceStatusMixin [C:4] [TYPE Module] [SEMANTICS git, status, diff, log, history, lock]
-# @LAYER: Infra
+# @LAYER Infrastructure
 # @BRIEF Status, diff, and commit history operations for GitService (all concurrent-safe via per-dashboard locks).
-# @RELATION USED_BY -> [GitService]
+# @RELATION CALLED_BY -> [GitService]
 
 from datetime import datetime
 
@@ -13,9 +13,9 @@ from src.core.logger import belief_scope, logger
 class GitServiceStatusMixin:
     # region _parse_status_porcelain [TYPE Function]
     # @PURPOSE: Parse git status --porcelain output into staged, modified, and untracked file lists.
-    # @PRE: `repo` is an open GitPython Repo instance.
-    # @POST: Returns (staged, modified, untracked) tuple of file path lists.
-    # @RATIONALE: Avoids repo.is_dirty() / repo.index.diff("HEAD") which internally
+    # @PRE  `repo` is an open GitPython Repo instance.
+    # @POST  Returns (staged, modified, untracked) tuple of file path lists.
+    # @RATIONALE  Avoids repo.is_dirty() / repo.index.diff("HEAD") which internally
     #   call git diff --cached, a flag unsupported in some Git environments (exit 129).
     #   Using git status --porcelain is self-contained and avoids the --cached flag entirely.
     def _parse_status_porcelain(self, repo) -> tuple[list[str], list[str], list[str]]:
@@ -52,9 +52,9 @@ class GitServiceStatusMixin:
 
     # region get_status [C:4] [TYPE Function] [SEMANTICS git,status,lock]
     # @PURPOSE: Get current repository status (concurrent-safe).
-    # @PRE: Repository for dashboard_id exists.
-    # @POST: Returns a dictionary representing the Git status.
-    # @RETURN: dict
+    # @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 self._locked(dashboard_id):
             with belief_scope("GitService.get_status"):
@@ -113,11 +113,11 @@ class GitServiceStatusMixin:
 
     # region get_diff [C:4] [TYPE Function] [SEMANTICS git,diff,lock]
     # @PURPOSE: Generate diff for a file or the whole repository (concurrent-safe).
-    # @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
+    # @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 self._locked(dashboard_id):
             with belief_scope("GitService.get_diff"):
@@ -132,10 +132,10 @@ class GitServiceStatusMixin:
 
     # region get_commit_history [C:4] [TYPE Function] [SEMANTICS git,history,lock]
     # @PURPOSE: Retrieve commit history for a repository (concurrent-safe).
-    # @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]
+    # @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 self._locked(dashboard_id):
             with belief_scope("GitService.get_commit_history"):