pyfcstm.diagnostics.inspect_render

Presentation renderers for inspect diagnostics.

This module converts pyfcstm.diagnostics.inspect.ModelInspect instances into human-readable or LLM-oriented text without changing the structured inspect JSON contract. The renderers are intentionally small and side-effect free so the CLI can offer multiple output formats while pyfcstm.diagnostics.inspect_model() and pyfcstm.diagnostics.inspect.ModelInspect.to_json() remain the single source of truth for machine-readable model data.

The module contains:

Inspect presentation helpers
Helper	Purpose
`render_inspect_human()`	Render a checker-style terminal report for humans.
`HumanRenderOptions`	Carry human-renderer presentation toggles such as ANSI color.
`render_inspect_llm_json()`	Render the stable compact JSON packet for LLM repair loops.
`render_inspect_llm_markdown()`	Render the stable Markdown packet for prompt composition.
`inspect_output_suffix_warning()`	Detect suspicious `--output` suffix and format combinations.

Example:

>>> from pyfcstm.diagnostics.inspect_render import inspect_output_suffix_warning
>>> inspect_output_suffix_warning("report.json", "human")
"output file 'report.json' looks like JSON, but inspect format is 'human'. Use '--format json' if you intended machine-readable JSON output."

INSPECT_LLM_SCHEMA_VERSION

pyfcstm.diagnostics.inspect_render.INSPECT_LLM_SCHEMA_VERSION = 'pyfcstm.inspect.llm.v1'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

SourceExcerptLine

class pyfcstm.diagnostics.inspect_render.SourceExcerptLine(line_number: int, text: str, caret: str | None = None)[source]

One source line included in a diagnostic source window.

Parameters:

line_number (int) – One-based source line number.
text (str) – Source line text without its trailing newline.
caret (Optional[str], optional) – Optional caret marker for the diagnostic anchor line.

Example:

>>> SourceExcerptLine(3, "state Idle;", None).text
'state Idle;'

SourceExcerpt

class pyfcstm.diagnostics.inspect_render.SourceExcerpt(line_number: int, text: str, caret: str, context_lines: Tuple[SourceExcerptLine, ...] = ())[source]

Source excerpt window anchored by a diagnostic span.

Parameters:

line_number (int) – One-based line number for the diagnostic anchor.
text (str) – Anchor source line text without its trailing newline.
caret (str) – Caret marker aligned to the diagnostic span on the anchor line.
context_lines (Tuple[SourceExcerptLine, ...], optional) – Source window around the anchor line. The window usually contains one line before and after the anchor when available.

Example:

>>> SourceExcerpt(2, "def int x = 0;", "^^^^").line_number
2

HumanRenderOptions

class pyfcstm.diagnostics.inspect_render.HumanRenderOptions(color_enabled: bool = False)[source]

Options controlling human inspect presentation details.

The options intentionally describe terminal presentation only. They do not change pyfcstm.diagnostics.inspect.ModelInspect.to_json() or any LLM renderer, which keeps machine-readable inspect output independent of ANSI styling decisions.

Parameters:: color_enabled (bool, optional) – Whether ANSI color should be emitted for the human renderer. Defaults to False so programmatic calls are plain ASCII unless the CLI explicitly enables color for an interactive terminal.

Example:

>>> HumanRenderOptions(color_enabled=True).color_enabled
True

inspect_output_suffix_warning

pyfcstm.diagnostics.inspect_render.inspect_output_suffix_warning(output_file: str | None, output_format: str) → str | None[source]

Return a warning for suspicious output suffix and format pairs.

The function never changes the requested format. It only reports cases where a filename extension strongly suggests that the user may have meant a different --format value.

Parameters:

output_file (Optional[str]) – Output path supplied to the CLI, or None for stdout.
output_format (str) – Requested inspect output format.

Returns:

Human-readable warning text, or None when the suffix is not suspicious.

Return type:

Optional[str]

Raises:

ValueError – If output_format is not a supported format.

Example:

>>> inspect_output_suffix_warning("report.json", "human") is not None
True
>>> inspect_output_suffix_warning("report.json", "json") is None
True

render_inspect_human

pyfcstm.diagnostics.inspect_render.render_inspect_human(report: Any, source_text: str | None = None, *, input_path: str | None = None, options: HumanRenderOptions | None = None) → str[source]

Render an inspect report as checker-style human-readable text.

Parameters:

report (pyfcstm.diagnostics.inspect.ModelInspect) – Inspect report returned by pyfcstm.diagnostics.inspect_model().
source_text (Optional[str], optional) – Optional FCSTM source text used to render source excerpts for diagnostics with spans.
input_path (Optional[str], optional) – Optional path shown in the report heading and locations.
options (pyfcstm.diagnostics.inspect_render.HumanRenderOptions, optional) – Optional presentation controls such as ANSI color.

Returns:

Human-readable report ending with a newline.

Return type:

str

Example:

>>> from pyfcstm.model import load_state_machine_from_text
>>> from pyfcstm.diagnostics import inspect_model
>>> model = load_state_machine_from_text('state Root { state Idle; [*] -> Idle; }')
>>> text = render_inspect_human(inspect_model(model), 'state Root { state Idle; [*] -> Idle; }')
>>> '[WARN] FCSTM Inspect Report' in text
True

render_inspect_llm_json

pyfcstm.diagnostics.inspect_render.render_inspect_llm_json(report: Any, source_text: str | None = None, *, input_path: str | None = None) → str[source]

Render an inspect report as a stable compact JSON packet for LLMs.

The packet is marked with INSPECT_LLM_SCHEMA_VERSION. This versioned contract is intended for downstream repair loops that need a compact, source-located, and provenance-aware diagnostic report.

Parameters:

report (pyfcstm.diagnostics.inspect.ModelInspect) – Inspect report returned by pyfcstm.diagnostics.inspect_model().
source_text (Optional[str], optional) – Optional source text for diagnostic excerpts.
input_path (Optional[str], optional) – Optional input path attached to the packet.

Returns:

Pretty-printed JSON packet ending with a newline.

Return type:

str

Example:

>>> from pyfcstm.model import load_state_machine_from_text
>>> from pyfcstm.diagnostics import inspect_model
>>> model = load_state_machine_from_text('state Root { state Idle; [*] -> Idle; }')
>>> text = render_inspect_llm_json(inspect_model(model), 'state Root { state Idle; [*] -> Idle; }')
>>> INSPECT_LLM_SCHEMA_VERSION in text
True

render_inspect_llm_markdown

pyfcstm.diagnostics.inspect_render.render_inspect_llm_markdown(report: Any, source_text: str | None = None, *, input_path: str | None = None) → str[source]

Render an inspect report as stable Markdown for LLM prompts.

Parameters:

report (pyfcstm.diagnostics.inspect.ModelInspect) – Inspect report returned by pyfcstm.diagnostics.inspect_model().
source_text (Optional[str], optional) – Optional source text for diagnostic excerpts.
input_path (Optional[str], optional) – Optional path shown in the heading and locations.

Returns:

Markdown report ending with a newline.

Return type:

str

Example:

>>> from pyfcstm.model import load_state_machine_from_text
>>> from pyfcstm.diagnostics import inspect_model
>>> model = load_state_machine_from_text('state Root { state Idle; [*] -> Idle; }')
>>> text = render_inspect_llm_markdown(inspect_model(model), 'state Root { state Idle; [*] -> Idle; }')
>>> '# FCSTM Inspect Report' in text
True