nc-gcode-interpreter 0.2.1__tar.gz → 0.2.3__tar.gz

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/CHANGELOG.md

@@ -4,6 +4,42 @@ Notable changes to **nc-gcode-interpreter**. The format loosely follows
 [Keep a Changelog](https://keepachangelog.com/); versions are git tags,
 released to PyPI.
 
+## [v0.2.3] - 2026-07-07
+
+### Added
+
+- `NcError.kind`: a stable, machine-readable string discriminating the error
+  class (e.g. `"unexpected_axis"`, `"undefined_variable"`, `"unknown_g_command"`,
+  `"parse_context"`), so a consumer can branch on the kind of error without
+  string-matching the formatted message. Present on every `NcError` alongside
+  the existing `line` / `column` / `context` / `line_text` location attributes
+  (#56).
+
+### Fixed
+
+- Validation/semantic errors now carry their source location. `Unexpected axis`,
+  and the "axis/reserved name used as a variable" definition errors, previously
+  raised an `NcError` with `line` / `column` / `context` / `line_text` all
+  `None`; they now anchor to the offending line (and expose its text), so an
+  editor can mark the exact spot - matching what syntactic parse errors already
+  did (#56).
+
+## [v0.2.2] - 2026-07-07
+
+### Added
+
+- Variable-change events on the batch path: `nc_to_batches(...,
+  include_variables=True)` exposes, once exhausted, a sparse `variable_events`
+  DataFrame (`row_idx` / `name_id` / `value`) plus a `variable_names` list -
+  the batch-path twin of the per-row `variables` dict `nc_to_rows` already
+  yields. `row_idx` is the output-row index a change is seen at (a change on a
+  variable-only block is attributed to the next output row), so replaying the
+  events reconstructs the symbol table at any row. Off by default (no cost).
+- `string_table` in the interpreter state dict: `DEF STRING` variables now
+  round-trip into `.state` / the `nc_to_dataframe` state tuple as
+  `state["string_table"]` (`dict[str, str]`), alongside the existing `axes` /
+  `symbol_table` / `translation` numeric tables (previously omitted).
+
 ## [v0.2.1] - 2026-07-07
 
 ### Added

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/Cargo.lock

@@ -506,7 +506,7 @@ checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "nc-gcode-interpreter"
-version = "0.2.1"
+version = "0.2.3"
 dependencies = [
  "arrow-array",
  "arrow-data",

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "nc-gcode-interpreter"
-version = "0.2.1"
+version = "0.2.3"
 edition = "2021"
 readme = "README.md"
 

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nc-gcode-interpreter
-Version: 0.2.1
+Version: 0.2.3
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: 3.12

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/python/nc_gcode_interpreter/__init__.py

@@ -498,6 +498,29 @@ class _BatchIterator:
     def state(self) -> dict | None:
         return self._inner.state
 
+    @property
+    def variable_events(self) -> "pl.DataFrame | None":
+        """Sparse variable-change events (``include_variables=True``).
+
+        A :class:`polars.DataFrame` with columns ``row_idx`` (the output-row
+        index the change is seen at), ``name_id`` (index into
+        :attr:`variable_names`) and ``value``. ``None`` unless the iterator was
+        created with ``include_variables=True``. Available once exhausted.
+        Replaying the events in order (decoding ``name_id`` via
+        :attr:`variable_names`) reconstructs the symbol table at any row, the
+        batch-path twin of the per-row ``variables`` dict ``nc_to_rows`` yields.
+        """
+        batch = self._inner.variable_events
+        return None if batch is None else pl.DataFrame(batch)
+
+    @property
+    def variable_names(self) -> list[str] | None:
+        """Variable names ``variable_events.name_id`` indexes into.
+
+        ``None`` unless ``include_variables=True``; available once exhausted.
+        """
+        return self._inner.variable_names
+
 
 def nc_to_batches(
     input: "TextFileLike | str | os.PathLike",
@@ -511,6 +534,7 @@ def nc_to_batches(
     allow_undefined_variables: bool = False,
     flatten_tolerance: float | None = None,
     include_line_numbers: bool = False,
+    include_variables: bool = False,
 ) -> _BatchIterator:
     """Interpret an NC program into a stream of columnar polars DataFrames.
 
@@ -541,6 +565,12 @@ def nc_to_batches(
     a loop, non-monotonic across a jump), never forward-filled. Default False
     leaves the schema unchanged.
 
+    With ``include_variables=True`` the iterator additionally exposes
+    ``variable_events`` (a sparse :class:`polars.DataFrame` of ``row_idx`` /
+    ``name_id`` / ``value``) and ``variable_names`` once exhausted — the
+    batch-path equivalent of the per-row ``variables`` dict :func:`nc_to_rows`
+    yields; replaying the events reconstructs the symbol table at any row.
+
     Example:
     --------
     >>> batches = nc_to_batches("G1 X10\\nX20 Y5", batch_size=1)
@@ -564,5 +594,6 @@ def nc_to_batches(
         input_is_path,
         flatten_tolerance,
         include_line_numbers,
+        include_variables,
     )
     return _BatchIterator(inner)

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/python/nc_gcode_interpreter/_internal.pyi

@@ -9,6 +9,10 @@ class NcError(ValueError):
     """NC parse/interpret error carrying structured location data. Subclasses
     ValueError so `except ValueError` keeps working."""
 
+    #: Stable, machine-readable discriminator for the error class (e.g.
+    #: ``"unexpected_axis"``, ``"undefined_variable"``), for branching without
+    #: matching the formatted message.
+    kind: str
     line: Optional[int]
     column: Optional[int]
     context: Optional[str]
@@ -43,8 +47,15 @@ def nc_to_batches(
     input_is_path: bool = False,
     flatten_tolerance: Optional[float] = None,
     include_line_numbers: bool = False,
+    include_variables: bool = False,
 ) -> Any:
-    """Interpret an NC program into an iterator of columnar polars DataFrames."""
+    """Interpret an NC program into an iterator of columnar polars DataFrames.
+
+    The returned iterator exposes ``state`` (dict with ``axes``,
+    ``symbol_table``, ``translation`` and ``string_table``) once exhausted, and
+    - when ``include_variables`` is set - ``variable_events`` (an Arrow batch of
+    ``row_idx`` / ``name_id`` / ``value``) and ``variable_names`` (list[str]).
+    """
     ...
 
 __all__ = ["nc_to_rows", "nc_to_batches"]

nc_gcode_interpreter-0.2.3/python/tests/test_batch_variables.py

@@ -0,0 +1,205 @@
+"""Batch-path variable-change events (#46) + `string_table` in the state dict.
+
+The streaming `nc_to_rows(include_variables=True)` path yields a per-row
+`variables` dict; the batch path (`nc_to_batches` / `nc_to_dataframe`) now
+surfaces the same information as a sparse side-table (`row_idx`, `name_id`,
+`value`) plus a `variable_names` list. These tests pin (a) parity of the
+ordered assignment sequence between the two paths and (b) that `DEF STRING`
+variables round-trip into the returned state dict.
+"""
+
+import polars as pl
+
+from nc_gcode_interpreter import nc_to_batches, nc_to_dataframe, nc_to_rows
+
+
+def _stream_sequence(program: str) -> list[tuple[str, float]]:
+    """Flat, ordered `(name, value)` assignment sequence from the stream."""
+    return [
+        (name, value)
+        for _line, _row, variables in nc_to_rows(program, include_variables=True)
+        for name, value in variables.items()
+    ]
+
+
+def _batch_sequence(it) -> list[tuple[str, float]]:
+    """Flat, ordered `(name, value)` sequence decoded from the batch events."""
+    events = it.variable_events
+    names = it.variable_names
+    return [
+        (names[name_id], value)
+        for name_id, value in zip(events["name_id"], events["value"])
+    ]
+
+
+def test_batch_variable_events_match_stream_simple():
+    program = "\n".join(
+        [
+            "DEF REAL Q=2.5",  # variable-only
+            "R1=0",            # variable-only
+            "X=R1",            # output row, no change
+            "X=Q",             # output row, no change
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)  # exhaust to populate variable_events / state
+    assert _batch_sequence(it) == _stream_sequence(program)
+
+
+def test_batch_variable_events_match_stream_while_loop():
+    # A WHILE loop where R1 changes once per iteration: the per-iteration
+    # counter events must appear on the batch path exactly as they do on the
+    # stream, in the same order.
+    program = "\n".join(
+        [
+            "DEF REAL Q=2.5",
+            "R1=0",
+            "WHILE R1<3",
+            "X=R1 Q=Q*2",  # output row that ALSO assigns a variable
+            "R1=R1+1",     # variable-only, per iteration
+            "ENDWHILE",
+            "X=Q",
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)
+    assert _batch_sequence(it) == _stream_sequence(program)
+
+
+def test_batch_variable_events_row_idx_reconstructs_symbol_table():
+    # Replaying every event reconstructs the final symbol table (minus the
+    # built-in TRUE/FALSE), mirroring the streaming accumulation invariant.
+    program = "\n".join(
+        [
+            "DEF REAL Q=1",
+            "R1=0",
+            "WHILE R1<3",
+            "X=R1 Q=Q*2",
+            "R1=R1+1",
+            "ENDWHILE",
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)
+    accumulated: dict[str, float] = {}
+    for name, value in _batch_sequence(it):
+        accumulated[name] = value
+    symbol_table = dict(it.state["symbol_table"])
+    for builtin in ("TRUE", "FALSE"):
+        symbol_table.pop(builtin)
+    assert accumulated == symbol_table
+
+    # row_idx is monotonic non-decreasing (events arrive in program order) and
+    # bounded by the number of output rows.
+    events = it.variable_events
+    row_idx = events["row_idx"].to_list()
+    assert row_idx == sorted(row_idx)
+
+
+def test_batch_variable_events_row_idx_aligns_with_output_rows():
+    # A change on a variable-only block is attributed to the NEXT output row;
+    # a change on an output row gets that row's own index.
+    program = "\n".join(
+        [
+            "R1=0",   # variable-only, before output row 0
+            "X=R1",   # output row 0
+            "R1=1",   # variable-only, before output row 1
+            "X=R1",   # output row 1
+        ]
+    )
+    it = nc_to_batches(program, include_variables=True)
+    list(it)
+    events = it.variable_events
+    names = it.variable_names
+    decoded = [
+        (row_idx, names[name_id], value)
+        for row_idx, name_id, value in zip(
+            events["row_idx"], events["name_id"], events["value"]
+        )
+    ]
+    assert decoded == [(0, "R1", 0.0), (1, "R1", 1.0)]
+
+
+def test_batch_variable_events_absent_without_flag():
+    it = nc_to_batches("R1=5\nX=R1")
+    list(it)
+    assert it.variable_events is None
+    assert it.variable_names is None
+
+
+def test_batch_variable_events_empty_when_no_assignments():
+    it = nc_to_batches("G1 X10\nX20 Y5", include_variables=True)
+    list(it)
+    assert isinstance(it.variable_events, pl.DataFrame)
+    assert it.variable_events.height == 0
+    assert it.variable_names == []
+
+
+def test_string_table_round_trips_through_state_dict():
+    program = "\n".join(
+        [
+            "DEF STRING[16] MSG",
+            'MSG="HELLO WORLD"',
+            "DEF STRING[8] TAG",
+            'TAG="ABC"',
+            "G1 X1",
+        ]
+    )
+    _df, state = nc_to_dataframe(program)
+    assert state["string_table"] == {"MSG": "HELLO WORLD", "TAG": "ABC"}
+    # The existing numeric sub-tables are untouched by the new key.
+    assert set(state) == {"axes", "symbol_table", "translation", "string_table"}
+    # The string variable never leaks into the numeric symbol table.
+    assert "MSG" not in state["symbol_table"]
+
+
+def test_string_table_on_streaming_and_batch_iterators():
+    program = 'DEF STRING[8] MSG\nMSG="HI"\nG1 X1'
+    rows = nc_to_rows(program)
+    list(rows)
+    assert rows.state["string_table"] == {"MSG": "HI"}
+
+    it = nc_to_batches(program)
+    list(it)
+    assert it.state["string_table"] == {"MSG": "HI"}
+
+
+def test_line_numbers_and_variables_compose_on_the_batch_path():
+    # include_line_numbers (#45) and include_variables (#46) share the batch
+    # path and were merged independently; requesting both at once must give the
+    # leading `line_no` column AND the sparse variable-event side-table, with
+    # `row_idx` still aligned to the emitted (line_no-carrying) output rows.
+    program = "\n".join(
+        [
+            "R1=0",          # variable-only, before output row 0
+            "WHILE R1<3",
+            "X=R1",          # output row (loop body, source line 3)
+            "R1=R1+1",       # variable-only
+            "ENDWHILE",
+            "X9",            # output row, source line 6
+        ]
+    )
+    it = nc_to_batches(
+        program,
+        batch_size=1_000_000,
+        include_line_numbers=True,
+        include_variables=True,
+    )
+    df = pl.concat(list(it), how="diagonal")
+
+    # line_no leads and tracks source lines (loop body repeats line 3).
+    assert df.columns[0] == "line_no"
+    assert df["line_no"].to_list() == [3, 3, 3, 6]
+    assert df["X"].to_list() == [0.0, 1.0, 2.0, 9.0]
+
+    # Variable events still decode independently of the line_no column.
+    names = it.variable_names
+    decoded = [
+        (row_idx, names[name_id], value)
+        for row_idx, name_id, value in zip(
+            it.variable_events["row_idx"],
+            it.variable_events["name_id"],
+            it.variable_events["value"],
+        )
+    ]
+    assert decoded == [(0, "R1", 0.0), (1, "R1", 1.0), (2, "R1", 2.0), (3, "R1", 3.0)]

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/python/tests/test_structured_errors.py

@@ -48,3 +48,44 @@ def test_str_is_still_the_full_message():
     with pytest.raises(NcError) as exc:
         nc_to_dataframe("X=R99\n")
     assert "Undefined variable" in str(exc.value)
+
+
+def test_kind_is_a_stable_machine_readable_discriminator():
+    # #56: consumers branch on `kind` instead of string-matching the message.
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("X=R99\n")
+    assert exc.value.kind == "undefined_variable"
+
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("G999 X1\n")
+    assert exc.value.kind == "unknown_g_command"
+
+    # Present (and stable) on every NcError, alongside the location attrs.
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("G1 X10\nX20 Y((\n")
+    assert exc.value.kind == "parse_context"
+
+
+def test_validation_error_carries_kind_and_location():
+    # #56: an undeclared axis is a validation error; it now reports both a
+    # stable kind AND the source location (previously all-None).
+    with pytest.raises(NcError) as exc:
+        # Q is not a declared axis; the frame instruction is on line 2.
+        nc_to_dataframe("G1 X0 Y0 F100\nTRANS Q=10\n")
+    e = exc.value
+    assert e.kind == "unexpected_axis"
+    assert e.line == 2
+    assert e.column is None
+    assert e.line_text is not None and "Q=10" in e.line_text
+    assert "Unexpected axis" in str(e)
+
+
+def test_axis_used_as_variable_carries_location():
+    # Declaring a variable with an axis name is a validation error that now
+    # anchors to the offending DEF line.
+    with pytest.raises(NcError) as exc:
+        nc_to_dataframe("DEF REAL X\n")
+    e = exc.value
+    assert e.kind == "axis_used_as_variable"
+    assert e.line == 1
+    assert e.line_text is not None and "X" in e.line_text

{nc_gcode_interpreter-0.2.1 → nc_gcode_interpreter-0.2.3}/src/errors.rs

@@ -99,11 +99,26 @@ To fix this, ensure that each block contains at most one M command.
         message: String,
     },
     #[error("Unexpected axis '{axis}'. Valid axes are: {axes}")]
-    UnexpectedAxis { axis: String, axes: String },
+    UnexpectedAxis {
+        axis: String,
+        axes: String,
+        /// Source location of the offending axis word. Not shown in the
+        /// formatted message, only exposed as data (see [`ParsingError::location`]).
+        line_no: usize,
+        preview: String,
+    },
     #[error("Cannot define a variable named '{name}', as it conflicts with an axis name")]
-    AxisUsedAsVariable { name: String },
+    AxisUsedAsVariable {
+        name: String,
+        line_no: usize,
+        preview: String,
+    },
     #[error("Cannot define a variable named '{name}', as it is a reserved block address (spline PW/SD/PL)")]
-    ReservedNameUsedAsVariable { name: String },
+    ReservedNameUsedAsVariable {
+        name: String,
+        line_no: usize,
+        preview: String,
+    },
     #[error(
         r#"
 Missing axis mapping on line {line_no}
@@ -280,16 +295,48 @@ impl ParsingError {
             | Self::JumpTargetNotFound { line_no, preview, .. }
             | Self::UnmatchedStructure { line_no, preview, .. }
             | Self::UnknownGCommand { line_no, preview, .. }
-            | Self::InvalidFunctionArity { line_no, preview, .. } => some(*line_no, None, None, Some(preview)),
+            | Self::InvalidFunctionArity { line_no, preview, .. }
+            // Semantic/validation errors: the offending block is known at raise
+            // time, so they anchor to a line (no column) like the others above.
+            | Self::UnexpectedAxis { line_no, preview, .. }
+            | Self::AxisUsedAsVariable { line_no, preview, .. }
+            | Self::ReservedNameUsedAsVariable { line_no, preview, .. } => some(*line_no, None, None, Some(preview)),
             Self::ParseError { .. }
             | Self::InvalidElementCount { .. }
             | Self::InvalidCondition
             | Self::UnexpectedOperator { .. }
             | Self::LoopLimit { .. }
-            | Self::StreamClosed
-            | Self::UnexpectedAxis { .. }
-            | Self::AxisUsedAsVariable { .. }
-            | Self::ReservedNameUsedAsVariable { .. } => None,
+            | Self::StreamClosed => None,
+        }
+    }
+
+    /// A stable, machine-readable discriminator for the error class, so a
+    /// consumer can branch on the kind of error without string-matching the
+    /// formatted message. Exposed to Python as the `NcError.kind` attribute.
+    /// These strings are part of the public API: keep them stable.
+    pub fn kind(&self) -> &'static str {
+        match self {
+            Self::ParsingContext { .. } => "parse_context",
+            Self::UnknownVariable { .. } => "unknown_variable",
+            Self::UndefinedVariable { .. } => "undefined_variable",
+            Self::UnexpectedRule { .. } => "unexpected_rule",
+            Self::ParseError { .. } => "parse_error",
+            Self::InvalidElementCount { .. } => "invalid_element_count",
+            Self::InvalidCondition => "invalid_condition",
+            Self::UnexpectedOperator { .. } => "unexpected_operator",
+            Self::LoopLimit { .. } => "loop_limit",
+            Self::StreamClosed => "stream_closed",
+            Self::TooManyMCommands { .. } => "too_many_m_commands",
+            Self::UnexpectedAxis { .. } => "unexpected_axis",
+            Self::AxisUsedAsVariable { .. } => "axis_used_as_variable",
+            Self::ReservedNameUsedAsVariable { .. } => "reserved_name_used_as_variable",
+            Self::MissingAxisMapping { .. } => "missing_axis_mapping",
+            Self::InvalidAxisIndex { .. } => "invalid_axis_index",
+            Self::UnsupportedStatement { .. } => "unsupported_statement",
+            Self::JumpTargetNotFound { .. } => "jump_target_not_found",
+            Self::UnmatchedStructure { .. } => "unmatched_structure",
+            Self::UnknownGCommand { .. } => "unknown_g_command",
+            Self::InvalidFunctionArity { .. } => "invalid_function_arity",
         }
     }
 }
@@ -333,4 +380,189 @@ mod tests {
         assert!(ParsingError::StreamClosed.location().is_none());
         assert!(ParsingError::InvalidCondition.location().is_none());
     }
+
+    #[test]
+    fn validation_errors_now_carry_a_location() {
+        // #56: semantic/validation errors (previously location-less) anchor to
+        // the offending line so an editor can mark the spot.
+        let axis = ParsingError::UnexpectedAxis {
+            axis: "QQ".to_string(),
+            axes: "X, Y, Z".to_string(),
+            line_no: 4,
+            preview: "TRANS QQ10".to_string(),
+        };
+        let loc = axis.location().expect("UnexpectedAxis now has a location");
+        assert_eq!((loc.line, loc.column), (4, None));
+        assert_eq!(loc.line_text.as_deref(), Some("TRANS QQ10"));
+
+        let dup = ParsingError::AxisUsedAsVariable {
+            name: "X".to_string(),
+            line_no: 2,
+            preview: "DEF REAL X".to_string(),
+        };
+        assert_eq!(dup.location().expect("has location").line, 2);
+    }
+
+    #[test]
+    fn kind_is_a_stable_per_variant_discriminator() {
+        // Exhaustive: `kind()` strings are public API, so pin every variant's
+        // value. The wildcard-free match in `kind()` forces a new variant to be
+        // handled there; this list forces its string to be chosen deliberately.
+        use crate::types::Rule;
+        let s = String::new;
+        let cases: Vec<(ParsingError, &str)> = vec![
+            (
+                ParsingError::ParsingContext {
+                    line_no: 1,
+                    column: None,
+                    preview: s(),
+                    context: s(),
+                    message: s(),
+                },
+                "parse_context",
+            ),
+            (
+                ParsingError::UnknownVariable {
+                    line_no: 1,
+                    preview: s(),
+                    variable: s(),
+                },
+                "unknown_variable",
+            ),
+            (
+                ParsingError::UndefinedVariable {
+                    line_no: 1,
+                    preview: s(),
+                    name: s(),
+                },
+                "undefined_variable",
+            ),
+            (
+                ParsingError::UnexpectedRule {
+                    rule: Rule::EOI,
+                    context: s(),
+                    line_no: 1,
+                    preview: s(),
+                    message: s(),
+                },
+                "unexpected_rule",
+            ),
+            (ParsingError::ParseError { message: s() }, "parse_error"),
+            (
+                ParsingError::InvalidElementCount { expected: 1, actual: 2 },
+                "invalid_element_count",
+            ),
+            (ParsingError::InvalidCondition, "invalid_condition"),
+            (
+                ParsingError::UnexpectedOperator { operator: s() },
+                "unexpected_operator",
+            ),
+            (ParsingError::LoopLimit { limit: s() }, "loop_limit"),
+            (ParsingError::StreamClosed, "stream_closed"),
+            (
+                ParsingError::TooManyMCommands {
+                    line_no: 1,
+                    preview: s(),
+                    message: s(),
+                },
+                "too_many_m_commands",
+            ),
+            (
+                ParsingError::UnexpectedAxis {
+                    axis: s(),
+                    axes: s(),
+                    line_no: 1,
+                    preview: s(),
+                },
+                "unexpected_axis",
+            ),
+            (
+                ParsingError::AxisUsedAsVariable {
+                    name: s(),
+                    line_no: 1,
+                    preview: s(),
+                },
+                "axis_used_as_variable",
+            ),
+            (
+                ParsingError::ReservedNameUsedAsVariable {
+                    name: s(),
+                    line_no: 1,
+                    preview: s(),
+                },
+                "reserved_name_used_as_variable",
+            ),
+            (
+                ParsingError::MissingAxisMapping {
+                    line_no: 1,
+                    preview: s(),
+                    axis: s(),
+                },
+                "missing_axis_mapping",
+            ),
+            (
+                ParsingError::InvalidAxisIndex {
+                    line_no: 1,
+                    preview: s(),
+                    axis: s(),
+                    index: 0,
+                },
+                "invalid_axis_index",
+            ),
+            (
+                ParsingError::UnsupportedStatement {
+                    line_no: 1,
+                    preview: s(),
+                    statement: s(),
+                    hint: s(),
+                },
+                "unsupported_statement",
+            ),
+            (
+                ParsingError::JumpTargetNotFound {
+                    line_no: 1,
+                    preview: s(),
+                    target: s(),
+                    search_direction: s(),
+                    hint: s(),
+                },
+                "jump_target_not_found",
+            ),
+            (
+                ParsingError::UnmatchedStructure {
+                    line_no: 1,
+                    preview: s(),
+                    message: s(),
+                },
+                "unmatched_structure",
+            ),
+            (
+                ParsingError::UnknownGCommand {
+                    line_no: 1,
+                    preview: s(),
+                    code: s(),
+                },
+                "unknown_g_command",
+            ),
+            (
+                ParsingError::InvalidFunctionArity {
+                    line_no: 1,
+                    preview: s(),
+                    name: s(),
+                    expected: 1,
+                    actual: 2,
+                },
+                "invalid_function_arity",
+            ),
+        ];
+        for (err, expected) in &cases {
+            assert_eq!(err.kind(), *expected, "kind mismatch for {err:?}");
+        }
+        // Every kind string is distinct (no two variants share a discriminator).
+        let mut kinds: Vec<&str> = cases.iter().map(|(_, k)| *k).collect();
+        kinds.sort_unstable();
+        let unique = kinds.len();
+        kinds.dedup();
+        assert_eq!(kinds.len(), unique, "duplicate kind discriminator");
+    }
 }