errors.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/registry/source/errors.py
 
# OCT-LINT: disable=tests_exist reason="Covered by oc_chat/tests/registry/source/test_scanner.py"
"""
Source-validation exception types for the AuthoredSource engine.
 
Purpose
-------
Carry the granular ``SRC_*`` failure code (Registry Source & Storage Spec V0.22
§10) on every condition the scanner / canonical loader / hashing layer raises,
so the ``regenerate`` pipeline (P1.4) can assemble the JSON error envelope and
operators/CI can branch on the exact cause.
 
Responsibilities
----------------
- Define ``SourceError`` (base) carrying ``code``/``records``/``hint``.
- Define ``SourceScanError`` (tree cannot be enumerated; ``scan_error``).
- Define ``SourceValidationError`` (a record/path/canonicalisation failure).
- Expose the P1.3-emitted ``SRC_*`` code constants.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - error construction
    L3 - offending record context
    L4 - code/hint assembly
 
Contracts
---------
- ``code`` is one of the durable §10 ``SRC_*`` strings (NOT a class name).
- ``records`` is a deterministically ordered list of offending file/field refs.
- P1.4 owns the full envelope assembly + the complete code enum; this module
  owns only the exception classes the P1.3 surface raises.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
"""
from __future__ import annotations
 
from typing import Optional, Sequence
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
# §10 SRC_* codes emitted by the P1.3 surface (scanner / canonical / hashing).
SRC_SCAN_FAILED = "SRC_SCAN_FAILED"
SRC_UNKNOWN_FILE = "SRC_UNKNOWN_FILE"
SRC_BAD_PHASE_PATH = "SRC_BAD_PHASE_PATH"
SRC_DUP_OR_STEM_MISMATCH = "SRC_DUP_OR_STEM_MISMATCH"
SRC_BAD_YAML = "SRC_BAD_YAML"
SRC_BAD_YAML_FEATURE = "SRC_BAD_YAML_FEATURE"
SRC_STRICT_TYPE = "SRC_STRICT_TYPE"
SRC_NOT_CANONICAL = "SRC_NOT_CANONICAL"
SRC_BAD_QUERY_PARAMS = "SRC_BAD_QUERY_PARAMS"
 
 
class SourceError(Exception):
    """Base for every AuthoredSource failure, carrying the §10 envelope fields."""
 
    def __init__(
        self,
        message: str,
        *,
        code: str,
        records: Optional[Sequence[str]] = None,
        hint: Optional[str] = None,
    ) -> None:
        super().__init__(message)
        self.code = code
        self.records: list[str] = list(records) if records else []
        self.hint = hint
 
 
class SourceScanError(SourceError):
    """The source tree cannot be fully enumerated/read (perm/symlink/encoding).
 
    Carries ``scan_error = {path, os_error}``; the envelope's
    ``raw_source_tree_hash`` is ``null`` for this class (§10).
    """
 
    def __init__(
        self,
        message: str,
        *,
        path: str,
        os_error: str,
        hint: Optional[str] = None,
    ) -> None:
        super().__init__(message, code=SRC_SCAN_FAILED, records=[path], hint=hint)
        self.scan_error = {"path": path, "os_error": os_error}
 
 
class SourceValidationError(SourceError):
    """A record/path/canonicalisation failure (unknown file, bad path shape,
    bad YAML, strict-type rejection, non-canonical bytes, bad query params)."""