Source code for fleetmesh_node.compartment.problem

"""Class-driven problem and runtime trouble definitions for compartments.

Every compartment declares what it is (SCHEMA, COMMANDS, NEEDS, STORES,
WORKERS, EVERY, CHANNELS, METRICS, LIFECYCLE). When a declaration is invalid,
`declaration_problems` collects `Problem` instances rather than loose strings,
carrying the surface, semantic code, target, and human-readable message.

Similarly, when a compartment is in an abnormal state, `trouble()` returns
`Trouble` instances carrying the fault code, severity, timestamp, and optional
remediation hint.

Both `Problem` and `Trouble` inherit from `str` so that:
  - String formatting (`str(p)`, `f"{p}"`) produces the sentence directly.
  - Substring checks (`'twice' in p`, `'relay' in t`) continue to pass.
  - List comparisons (`[p] == ['message']`) evaluate True against raw strings.
  - Existing callers, tests, and json encoders require zero breaking changes.
"""
from __future__ import annotations

from typing import Any, Mapping, Optional, TypeVar, TypedDict

P = TypeVar('P', bound='Problem')
T_tr = TypeVar('T_tr', bound='Trouble')


[docs]class ProblemDict(TypedDict, total=False): """Concrete dictionary structure for a declaration problem.""" message: str surface: str code: str target: str hint: Optional[str] reference: str expected: str got: str owner: str
[docs]class Problem(str): """A structured declaration problem. Subclasses str for complete backwards compatibility with tests and callers expecting str messages, while exposing structured metadata for linters, checkers, and IDE diagnostics. """ surface: str code: str target: str message: str hint: Optional[str]
[docs] def __new__( cls: type[P], message: str, *, surface: str = '', code: str = '', target: str = '', hint: Optional[str] = None, ) -> P: obj = super().__new__(cls, message) obj.surface = str(surface) obj.code = str(code) obj.target = str(target) obj.message = str(message) obj.hint = hint return obj
[docs] def to_dict(self) -> ProblemDict: """Dictionary representation for structured reporting.""" d: ProblemDict = { 'message': self.message, 'surface': self.surface, 'code': self.code, } if self.target: d['target'] = self.target if self.hint is not None: d['hint'] = self.hint return d
[docs]class DuplicateProblem(Problem): """An item was declared twice on the same surface."""
[docs] def __new__( cls, surface: str, target: str, message: Optional[str] = None, hint: Optional[str] = None, ) -> DuplicateProblem: msg = message if message is not None else f"{surface} declares {target!r} twice" return super().__new__( cls, msg, surface=surface, code='duplicate', target=target, hint=hint or 'remove or rename the duplicate declaration', )
[docs]class InvalidIdentifierProblem(Problem): """An identifier name does not follow the required naming pattern."""
[docs] def __new__( cls, surface: str, target: str, message: Optional[str] = None, hint: Optional[str] = None, ) -> InvalidIdentifierProblem: msg = message if message is not None else f"{surface} identifier {target!r} is not a valid identifier" return super().__new__( cls, msg, surface=surface, code='invalid_identifier', target=target, hint=hint or 'identifiers must start with a letter/underscore and contain only alphanumeric characters', )
[docs]class ReferenceProblem(Problem): """A declaration references an entity that is unknown or missing.""" reference: str
[docs] def __new__( cls, surface: str, target: str, reference: str, message: Optional[str] = None, hint: Optional[str] = None, ) -> ReferenceProblem: msg = message if message is not None else f"{surface} {target} references unknown {reference!r}" obj = super().__new__( cls, msg, surface=surface, code='unknown_reference', target=target, hint=hint, ) obj.reference = str(reference) return obj
[docs] def to_dict(self) -> ProblemDict: d = super().to_dict() d['reference'] = self.reference return d
[docs]class TypeMismatchProblem(Problem): """A declaration entry has the wrong type or does not implement the expected class.""" expected: str got: str
[docs] def __new__( cls, surface: str, expected: str, got: str, message: Optional[str] = None, hint: Optional[str] = None, ) -> TypeMismatchProblem: msg = message if message is not None else f"{surface} holds {expected}, not {got}" obj = super().__new__( cls, msg, surface=surface, code='type_mismatch', target=got, hint=hint or f"use instances of {expected}", ) obj.expected = str(expected) obj.got = str(got) return obj
[docs] def to_dict(self) -> ProblemDict: d = super().to_dict() d['expected'] = self.expected d['got'] = self.got return d
[docs]class ShadowingProblem(Problem): """A declared key would shadow a method or class attribute.""" owner: str
[docs] def __new__( cls, surface: str, target: str, owner: str, message: Optional[str] = None, hint: Optional[str] = None, ) -> ShadowingProblem: msg = message if message is not None else f"{surface} {target} would shadow {owner}.{target}; pick another key" obj = super().__new__( cls, msg, surface=surface, code='shadows_attribute', target=target, hint=hint or 'pick another key to avoid overwriting attributes', ) obj.owner = str(owner) return obj
[docs] def to_dict(self) -> ProblemDict: d = super().to_dict() d['owner'] = self.owner return d
[docs]class IncompatibleProblem(Problem): """Two declarations or declarations and method implementations are incompatible."""
[docs] def __new__( cls, surface: str, target: str, message: str, hint: Optional[str] = None, ) -> IncompatibleProblem: return super().__new__( cls, message, surface=surface, code='incompatible', target=target, hint=hint, )
[docs]class Problems(list[Any]): """A list of Problem instances providing query methods and surface filtering."""
[docs] def for_surface(self, surface: str) -> list[Problem]: """Return all problems recorded for a specific declaration surface.""" return [p for p in self if isinstance(p, Problem) and p.surface == surface]
[docs] def by_code(self, code: str) -> list[Problem]: """Return all problems with a specific semantic code.""" return [p for p in self if isinstance(p, Problem) and p.code == code]
[docs] def surfaces(self) -> set[str]: """Set of surfaces that have problems.""" return {p.surface for p in self if isinstance(p, Problem) and p.surface}
[docs] def codes(self) -> set[str]: """Set of unique problem codes.""" return {p.code for p in self if isinstance(p, Problem) and p.code}
[docs] def to_dicts(self) -> list[ProblemDict]: """Serialize all problems to dictionaries.""" return [p.to_dict() if isinstance(p, Problem) else {'message': str(p), 'surface': '', 'code': ''} for p in self]
[docs] def add( self, problem_or_message: Any, *, surface: str = '', code: str = '', target: str = '', hint: Optional[str] = None, ) -> None: """Append a problem or wrap a string message into a Problem.""" if isinstance(problem_or_message, Problem): self.append(problem_or_message) else: self.append(Problem(str(problem_or_message), surface=surface, code=code, target=target, hint=hint))
# ---- Runtime Trouble --------------------------------------------------------
[docs]class TroubleDict(TypedDict, total=False): """Concrete dictionary structure for runtime trouble.""" message: str code: str severity: str compartment: str since: Optional[int] hint: Optional[str] metadata: Mapping[str, Any]
[docs]class Trouble(str): """What an operator should be told without having to ask for it. Subclasses str so that existing tests asserting against `trouble()` strings, substring matches (`'relay' in t`), list equality (`[t] == ['foo']`), and string formatting continue to work 100% identically without breaking changes. """ code: str compartment: str message: str severity: str since: Optional[int] hint: Optional[str] metadata: Mapping[str, Any]
[docs] def __new__( cls: type[T_tr], message: str, *, code: str = 'fault', compartment: str = '', severity: str = 'trouble', since: Optional[int] = None, hint: Optional[str] = None, **metadata: Any, ) -> T_tr: obj = super().__new__(cls, message) obj.code = str(code) obj.compartment = str(compartment) obj.message = str(message) obj.severity = str(severity) obj.since = since obj.hint = hint obj.metadata = metadata return obj
[docs] def to_dict(self) -> TroubleDict: """Serialize to a JSON-compatible dictionary.""" d: TroubleDict = { 'message': self.message, 'code': self.code, 'severity': self.severity, } if self.compartment: d['compartment'] = self.compartment if self.since is not None: d['since'] = self.since if self.hint is not None: d['hint'] = self.hint if self.metadata: d['metadata'] = self.metadata return d
[docs]class TroubleList(list[Any]): """A list of Trouble items offering filtering and serialization."""
[docs] def for_compartment(self, compartment: str) -> list[Trouble]: """Filter troubles belonging to a specific compartment.""" return [t for t in self if isinstance(t, Trouble) and t.compartment == compartment]
[docs] def by_code(self, code: str) -> list[Trouble]: """Filter troubles by fault code.""" return [t for t in self if isinstance(t, Trouble) and t.code == code]
[docs] def by_severity(self, severity: str) -> list[Trouble]: """Filter troubles by severity ('trouble', 'warning', 'fatal', etc.).""" return [t for t in self if isinstance(t, Trouble) and t.severity == severity]
[docs] def codes(self) -> set[str]: """Set of unique trouble codes.""" return {t.code for t in self if isinstance(t, Trouble) and t.code}
[docs] def compartments(self) -> set[str]: """Set of compartments reporting trouble.""" return {t.compartment for t in self if isinstance(t, Trouble) and t.compartment}
[docs] def to_dicts(self) -> list[TroubleDict]: """Serialize all troubles to dictionaries.""" return [t.to_dict() if isinstance(t, Trouble) else {'message': str(t), 'code': 'fault', 'severity': 'trouble'} for t in self]
[docs] def add( self, trouble_or_message: Any, *, code: str = 'fault', compartment: str = '', severity: str = 'trouble', since: Optional[int] = None, hint: Optional[str] = None, **kw: Any, ) -> None: """Append a trouble item or wrap a raw string into a Trouble instance.""" if isinstance(trouble_or_message, Trouble): self.append(trouble_or_message) else: self.append(Trouble( str(trouble_or_message), code=code, compartment=compartment, severity=severity, since=since, hint=hint, **kw, ))
# ---- Runtime Notes ---------------------------------------------------------- T_note = TypeVar('T_note', bound='Note')
[docs]class NoteDict(TypedDict, total=False): """Concrete dictionary structure for runtime notes.""" message: str topic: str level: str compartment: str since: Optional[int] metadata: Mapping[str, Any]
[docs]class Note(str): """What an operator would want to read, that is not a fault. A relay cooling after a rate-limit, a peer that announced it is leaving: the node behaving, and the reason a quiet mesh is quiet. Kept apart from `trouble()` so no reader has to classify prose. Subclasses str so that existing tests asserting against `notes()` strings, substring matches, or list equality continue to work 100% identically. """ topic: str compartment: str message: str level: str since: Optional[int] metadata: Mapping[str, Any]
[docs] def __new__( cls: type[T_note], message: str, *, topic: str = 'general', compartment: str = '', level: str = 'info', since: Optional[int] = None, **metadata: Any, ) -> T_note: obj = super().__new__(cls, message) obj.topic = str(topic) obj.compartment = str(compartment) obj.message = str(message) obj.level = str(level) obj.since = since obj.metadata = metadata return obj
[docs] def to_dict(self) -> NoteDict: """Serialize to a JSON-compatible dictionary.""" d: NoteDict = { 'message': self.message, 'topic': self.topic, 'level': self.level, } if self.compartment: d['compartment'] = self.compartment if self.since is not None: d['since'] = self.since if self.metadata: d['metadata'] = self.metadata return d
[docs]class NoteList(list[Any]): """A list of Note items offering filtering and serialization."""
[docs] def for_compartment(self, compartment: str) -> list[Note]: """Filter notes belonging to a specific compartment.""" return [n for n in self if isinstance(n, Note) and n.compartment == compartment]
[docs] def by_topic(self, topic: str) -> list[Note]: """Filter notes by topic.""" return [n for n in self if isinstance(n, Note) and n.topic == topic]
[docs] def by_level(self, level: str) -> list[Note]: """Filter notes by level ('info', 'notice', 'debug', etc.).""" return [n for n in self if isinstance(n, Note) and n.level == level]
[docs] def topics(self) -> set[str]: """Set of unique note topics.""" return {n.topic for n in self if isinstance(n, Note) and n.topic}
[docs] def compartments(self) -> set[str]: """Set of compartments reporting notes.""" return {n.compartment for n in self if isinstance(n, Note) and n.compartment}
[docs] def to_dicts(self) -> list[NoteDict]: """Serialize all notes to dictionaries.""" return [n.to_dict() if isinstance(n, Note) else {'message': str(n), 'topic': 'general', 'level': 'info'} for n in self]
[docs] def add( self, note_or_message: Any, *, topic: str = 'general', compartment: str = '', level: str = 'info', since: Optional[int] = None, **kw: Any, ) -> None: """Append a note item or wrap a raw string into a Note instance.""" if isinstance(note_or_message, Note): self.append(note_or_message) else: self.append(Note( str(note_or_message), topic=topic, compartment=compartment, level=level, since=since, **kw, ))