fix(export): move ErrorCode to models to avoid Flask in utils (PR #73)

Extract ErrorCode to models/error_codes.py so export_engine no longer
transitively imports Flask via api. Document export-phase exc handling.

Author: clean6378-max-it

api/error_codes.py

@@ -1,22 +1,12 @@
-"""Stable machine-readable error codes for API JSON error responses."""
+"""HTTP error envelope helpers; :class:`ErrorCode` lives in :mod:`models.error_codes`."""
 
 from __future__ import annotations
 
-from enum import StrEnum
-
 from flask import Response, jsonify
 
+from models.error_codes import ErrorCode
 
-class ErrorCode(StrEnum):
-    SEARCH_INVALID_LIMIT = "SEARCH_INVALID_LIMIT"
-    INVALID_PATH = "INVALID_PATH"
-    SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
-    INVALID_REQUEST_BODY = "INVALID_REQUEST_BODY"
-    INVALID_SINCE_MODE = "INVALID_SINCE_MODE"
-    PARSE_ERROR = "PARSE_ERROR"
-    EXPORT_NOTHING_TO_EXPORT = "EXPORT_NOTHING_TO_EXPORT"
-    EXPORT_ALL_FAILED = "EXPORT_ALL_FAILED"
-    INTERNAL_ERROR = "INTERNAL_ERROR"
+__all__ = ["ErrorCode", "error_response"]
 
 
 def error_response(

models/error_codes.py

@@ -0,0 +1,17 @@
+"""Stable machine-readable error codes (shared by API and utils; no Flask dependency)."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class ErrorCode(StrEnum):
+    SEARCH_INVALID_LIMIT = "SEARCH_INVALID_LIMIT"
+    INVALID_PATH = "INVALID_PATH"
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
+    INVALID_REQUEST_BODY = "INVALID_REQUEST_BODY"
+    INVALID_SINCE_MODE = "INVALID_SINCE_MODE"
+    PARSE_ERROR = "PARSE_ERROR"
+    EXPORT_NOTHING_TO_EXPORT = "EXPORT_NOTHING_TO_EXPORT"
+    EXPORT_ALL_FAILED = "EXPORT_ALL_FAILED"
+    INTERNAL_ERROR = "INTERNAL_ERROR"

utils/export_engine.py

@@ -9,7 +9,7 @@
 from datetime import date, datetime, timezone
 from typing import Any, Callable, Literal, Protocol
 
-from api.error_codes import ErrorCode
+from models.error_codes import ErrorCode
 from models.project import ProjectDict, SessionListItemDict
 from models.session import SessionDict, SessionMetadataDict
 from models.stats import SessionStatsDict
@@ -74,7 +74,11 @@ def failure_code_for_exception(
     *,
     phase: Literal["parse", "export"] = "parse",
 ) -> ErrorCode:
-    """Map an export exception to a stable :class:`ErrorCode`."""
+    """Map an export exception to a stable :class:`ErrorCode`.
+
+    Export-phase failures always map to ``INTERNAL_ERROR``; ``exc`` is not
+    inspected on that path (no per-type export codes yet).
+    """
     if phase == "export":
         return ErrorCode.INTERNAL_ERROR
     if isinstance(exc, EXPORT_ERRORS):