refactor: Standardize error handling patterns across codebase

Comprehensive error handling improvements addressing inconsistent patterns:

• Created markitect/exceptions.py with complete domain-specific exception hierarchy
  - MarkitectError base class with context and cause chaining support
  - Specific exceptions for Document, AST, Cache, Database, Schema operations
  - Built-in logging and context preservation

• Fixed overly broad exception handling in tddai modules:
  - issue_fetcher.py: Replace generic Exception with specific Gitea errors
  - project_manager.py: Proper error translation with context preservation
  - coverage_analyzer.py: Replace silent suppression with logging

• Enhanced cache_service.py error handling:
  - Specific OSError/PermissionError handling for file operations
  - Logging integration for unexpected errors
  - Preserved error collection and reporting

• Implemented proper exception chaining patterns:
  - All error translations use `raise ... from e` for debugging
  - Preserved original exception context and stack traces
  - Added docstring declarations of raised exceptions

• Benefits:
  - Eliminates silent error suppression and debugging black holes
  - Provides specific, actionable error messages
  - Preserves full error context for troubleshooting
  - Establishes consistent patterns for future development

Resolves issue #21: Error handling standardization

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

tddai/coverage_analyzer.py

@@ -246,8 +246,21 @@ class CoverageAnalyzer:
                     coverage_keywords=coverage_keywords,
                     related_issue=related_issue
                 ))
+            except (OSError, IOError, UnicodeDecodeError) as e:
+                # Skip files that can't be read due to file system or encoding issues
+                # Log the issue but continue processing other files
+                import logging
+                logging.getLogger(__name__).warning(
+                    f"Could not read test file {test_file}: {e}"
+                )
+                continue
             except Exception as e:
-                # Skip files that can't be read
+                # Unexpected errors should be logged but not silently ignored
+                import logging
+                logging.getLogger(__name__).error(
+                    f"Unexpected error processing test file {test_file}: {e}",
+                    exc_info=True
+                )
                 continue
 
         return existing_tests

tddai/issue_fetcher.py

@@ -8,6 +8,7 @@ maintaining backwards compatibility while using the cleaner API.
 from typing import List, Dict, Any
 
 from gitea import GiteaClient, Issue as GiteaIssue, GiteaConfig
+from gitea.exceptions import GiteaError, GiteaNotFoundError, GiteaAuthError, GiteaApiError
 from .config import get_config
 from .exceptions import IssueError
 
@@ -26,27 +27,54 @@ class IssueFetcher:
         self.gitea_client = GiteaClient(gitea_config)
 
     def fetch_issue(self, issue_number: int) -> Issue:
-        """Fetch a specific issue by number."""
+        """Fetch a specific issue by number.
+
+        Raises:
+            IssueError: When issue cannot be fetched (with specific context)
+        """
         try:
             return self.gitea_client.issues.get(issue_number)
-        except Exception as e:
-            # Convert gitea exceptions to IssueError for backwards compatibility
-            raise IssueError(f"Failed to fetch issue #{issue_number}: {e}")
+        except GiteaNotFoundError as e:
+            raise IssueError(f"Issue #{issue_number} not found") from e
+        except GiteaAuthError as e:
+            raise IssueError(f"Authentication failed when fetching issue #{issue_number}") from e
+        except GiteaApiError as e:
+            raise IssueError(f"API error fetching issue #{issue_number}: {e}") from e
+        except GiteaError as e:
+            raise IssueError(f"Gitea error fetching issue #{issue_number}: {e}") from e
 
     def fetch_issues(self, state: str = "all") -> List[Issue]:
-        """Fetch all issues with optional state filter."""
+        """Fetch all issues with optional state filter.
+
+        Args:
+            state: Issue state filter ("all", "open", "closed")
+
+        Raises:
+            IssueError: When issues cannot be fetched (with specific context)
+        """
         try:
             return self.gitea_client.issues.list(state=state)
-        except Exception as e:
-            # Convert gitea exceptions to IssueError for backwards compatibility
-            raise IssueError(f"Failed to fetch issues: {e}")
+        except GiteaAuthError as e:
+            raise IssueError("Authentication failed when fetching issues") from e
+        except GiteaApiError as e:
+            raise IssueError(f"API error fetching issues with state '{state}': {e}") from e
+        except GiteaError as e:
+            raise IssueError(f"Gitea error fetching issues: {e}") from e
 
     def fetch_open_issues(self) -> List[Issue]:
-        """Fetch only open issues."""
+        """Fetch only open issues.
+
+        Raises:
+            IssueError: When open issues cannot be fetched (with specific context)
+        """
         try:
             return self.gitea_client.issues.list_open()
-        except Exception as e:
-            raise IssueError(f"Failed to fetch open issues: {e}")
+        except GiteaAuthError as e:
+            raise IssueError("Authentication failed when fetching open issues") from e
+        except GiteaApiError as e:
+            raise IssueError(f"API error fetching open issues: {e}") from e
+        except GiteaError as e:
+            raise IssueError(f"Gitea error fetching open issues: {e}") from e
 
     def get_issue_data_dict(self, issue_number: int) -> Dict[str, Any]:
         """Get issue data as dictionary for workspace creation."""

tddai/project_manager.py

@@ -10,6 +10,7 @@ from typing import Dict, Any, List, Optional
 
 from gitea import GiteaClient, GiteaConfig
 from gitea.models import ProjectState, Priority, Milestone as GiteaMilestone, Label as GiteaLabel
+from gitea.exceptions import GiteaError, GiteaNotFoundError, GiteaAuthError, GiteaApiError
 from .config import get_config
 from .exceptions import IssueError
 
@@ -32,7 +33,16 @@ class ProjectManager:
         self.gitea_client = GiteaClient(gitea_config)
 
     def _make_api_call(self, method: str, url: str, data: Dict[str, Any] = None) -> Dict[str, Any]:
-        """Make authenticated API call to Gitea (kept for backwards compatibility)."""
+        """Make authenticated API call to Gitea (kept for backwards compatibility).
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            url: API endpoint URL
+            data: Optional request data
+
+        Raises:
+            IssueError: When API call fails (with specific context)
+        """
         # This method is kept for backwards compatibility but now delegates to the gitea client
         # For new code, use the gitea_client directly
         try:
@@ -45,8 +55,16 @@ class ProjectManager:
                 return self._issue_to_dict(issue)
             else:
                 raise IssueError(f"Legacy API call not supported: {method} {url}")
-        except Exception as e:
-            raise IssueError(f"API call failed: {e}")
+        except GiteaNotFoundError as e:
+            raise IssueError(f"Resource not found for {method} {url}") from e
+        except GiteaAuthError as e:
+            raise IssueError(f"Authentication failed for {method} {url}") from e
+        except GiteaApiError as e:
+            raise IssueError(f"API error for {method} {url}: {e}") from e
+        except GiteaError as e:
+            raise IssueError(f"Gitea error for {method} {url}: {e}") from e
+        except (ValueError, IndexError) as e:
+            raise IssueError(f"Invalid URL format for {method} {url}") from e
 
     def _issue_to_dict(self, issue) -> Dict[str, Any]:
         """Convert Issue object to dict for backwards compatibility."""