pyfcstm.diagnostics.sink

Runtime sink for emitting pyfcstm.utils.validate.ModelDiagnostic.

The sink lets a single pass of model construction (or, later, design-health inspection) operate in two modes through one code path:

• strict (the default) — each emit() raises a pyfcstm.utils.validate.ModelValidationError immediately, carrying the diagnostic just produced plus any earlier ones. This preserves the pre-PR-2 behavior where the very first semantic error aborts the build.

• collect — emit() appends to an internal list and returns; the caller is expected to call finalize() (or read diagnostics directly) at the end of the pass to inspect / surface every diagnostic found, even though the resulting model may be partial.

Downstream consumers (LLM agent loops, IDE integrations, the future jsfcstm visualization layer) dispatch on ModelDiagnostic.code. The sink is purely a runtime helper — the contract surface is the diagnostic objects themselves, not this class.

DiagnosticSink

class pyfcstm.diagnostics.sink.DiagnosticSink(collect: bool = False)

Collects ModelDiagnostic objects emitted during a pass.

Parameters:

collect (bool) – When False (the default), every emit() call raises ModelValidationError immediately, carrying the accumulated diagnostics. When True, errors are accumulated and the caller decides when to surface them.

Example:

>>> from pyfcstm.diagnostics.sink import DiagnosticSink
>>> from pyfcstm.utils import ModelDiagnostic
>>> sink = DiagnosticSink(collect=True)
>>> sink.emit(ModelDiagnostic(code='E_X', severity='error', message='x'))
>>> sink.emit(ModelDiagnostic(code='E_Y', severity='error', message='y'))
>>> [d.code for d in sink.diagnostics]
['E_X', 'E_Y']
>>> sink.has_errors()
True

__init__(collect: bool = False) → None

property collect: bool

Returns:

True if the sink accumulates diagnostics, False if it raises immediately.

Return type:

bool

property diagnostics: List[ModelDiagnostic]

Returns:

A snapshot copy of the diagnostics accumulated so far.

Return type:

List[ModelDiagnostic]

emit(diagnostic: ModelDiagnostic) → None

Record a diagnostic. In strict mode, raise immediately.

Parameters:

diagnostic (pyfcstm.utils.validate.ModelDiagnostic) – The structured diagnostic to record.

Raises:

pyfcstm.utils.validate.ModelValidationError – When the sink is in strict mode (the default) and the diagnostic has error severity.

finalize_or_raise() → None

In collect mode, raise a single ModelValidationError carrying all accumulated error diagnostics if any are present. In strict mode this is a no-op (errors already raised at emit time).

Raises:

pyfcstm.utils.validate.ModelValidationError – When collect mode accumulated at least one error-severity diagnostic.

has_errors() → bool

Returns:

True if at least one accumulated diagnostic has severity == 'error'.

Return type:

bool