sysml-windtrader 0.2.3__tar.gz → 0.2.4__tar.gz

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 <!-- version list -->
 
+## v0.2.4 (2026-10-17)
+
+### 🐛 Bug Fixes
+
+- Normalize any process exit code outside the documented 0/2/3 contract to **3**
+  (runtime error) in `CommandResult` (and thus the CLI). A JVM startup failure on an
+  old JRE (e.g. `UnsupportedClassVersionError` hitting the Java-21-compiled
+  `windtrader-java` 0.2.0 JAR) previously leaked a foreign code like **1**, breaking
+  the contract and making `is_runtime_error` (and CLI exit-code branching) miss the
+  case. The underlying JVM detail is preserved on `stderr`.
+- Add a Java-executable override so users with an old default `java` can point the
+  wrapper at a Java 21+ JVM: `WINDTRADER_JAVA` (explicit path) → `JAVA_HOME/bin/java`
+  → `java` on PATH.
+
+### 📝 Documentation
+
+- README: state the **Java 21+** requirement in Installation; document the exit-code
+  normalization and the Java-executable resolution order in Exit Code Contract and
+  Configuration.
+- pyproject description: note "requires Java 21+".
+
 ## v0.2.3 (2026-10-17)
 
 ### 📝 Documentation

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: sysml-windtrader
-Version: 0.2.3
-Summary: Python wrapper around windtrader-java for SysML v2 parse-only validation.
+Version: 0.2.4
+Summary: Python wrapper around windtrader-java for SysML v2 parse-only validation (requires Java 21+).
 Author: Westfall-io
 License: MIT License
         
@@ -80,7 +80,11 @@ Or for development:
 pip install -e ".[dev]"
 ```
 
-Java **must** be available on your system (CI uses Temurin JDK).
+**Java requirement:** the default `windtrader-java` release (0.2.x) is compiled for
+**Java 21** (class file version 65). Java **21 or newer** must be available on your
+system (CI uses Temurin JDK 21). If your default `java` is older, point the wrapper at a
+Java 21+ JVM via `WINDTRADER_JAVA` (explicit executable path) or `JAVA_HOME` — see
+[Configuration](#configuration).
 
 ---
 
@@ -199,7 +203,14 @@ The Java validator defines:
 | 2         | Invalid SysML      |
 | 3         | Runtime error      |
 
-Python preserves these codes exactly.
+Python preserves these codes exactly. Any process exit code **outside** (0, 2, 3) —
+for example the JVM's own startup failure code (1) when an old Java hits a
+Java-21-compiled JAR — is normalized to **3** (runtime error), so the contract never
+leaks a foreign code. The underlying JVM detail is kept on `stderr` (e.g.
+`UnsupportedClassVersionError ... class file version 65.0 ... only recognizes ... 62.0`).
+
+In the Python API, `CommandResult.exit_code` is always one of 0/2/3; `is_invalid_syntax`
+is `exit_code == 2` and `is_runtime_error` is `exit_code not in (0, 2)` (i.e. 3).
 
 ---
 
@@ -210,6 +221,13 @@ Environment variables:
 - `WINDTRADER_CACHE_DIR` – override JAR cache directory
 - `WINDTRADER_JAVA_REPO` – override GitHub repo for JAR downloads
 - `WINDTRADER_JAVA_STABLE_ASSET` – explicit asset URL (optional)
+- `WINDTRADER_JAVA` – explicit path to a `java` executable (or a JVM launcher) to use
+  instead of `java` on PATH. Handy on machines whose default Java is too old for the
+  target JAR — set it to a Java 21+ executable.
+- `JAVA_HOME` – if set (and `WINDTRADER_JAVA` is not), the wrapper uses
+  `<JAVA_HOME>/bin/java` as the Java executable.
+
+Java executable resolution order: `WINDTRADER_JAVA` → `JAVA_HOME/bin/java` → `java` on PATH.
 
 ---
 

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/README.md

@@ -42,7 +42,11 @@ Or for development:
 pip install -e ".[dev]"
 ```
 
-Java **must** be available on your system (CI uses Temurin JDK).
+**Java requirement:** the default `windtrader-java` release (0.2.x) is compiled for
+**Java 21** (class file version 65). Java **21 or newer** must be available on your
+system (CI uses Temurin JDK 21). If your default `java` is older, point the wrapper at a
+Java 21+ JVM via `WINDTRADER_JAVA` (explicit executable path) or `JAVA_HOME` — see
+[Configuration](#configuration).
 
 ---
 
@@ -161,7 +165,14 @@ The Java validator defines:
 | 2         | Invalid SysML      |
 | 3         | Runtime error      |
 
-Python preserves these codes exactly.
+Python preserves these codes exactly. Any process exit code **outside** (0, 2, 3) —
+for example the JVM's own startup failure code (1) when an old Java hits a
+Java-21-compiled JAR — is normalized to **3** (runtime error), so the contract never
+leaks a foreign code. The underlying JVM detail is kept on `stderr` (e.g.
+`UnsupportedClassVersionError ... class file version 65.0 ... only recognizes ... 62.0`).
+
+In the Python API, `CommandResult.exit_code` is always one of 0/2/3; `is_invalid_syntax`
+is `exit_code == 2` and `is_runtime_error` is `exit_code not in (0, 2)` (i.e. 3).
 
 ---
 
@@ -172,6 +183,13 @@ Environment variables:
 - `WINDTRADER_CACHE_DIR` – override JAR cache directory
 - `WINDTRADER_JAVA_REPO` – override GitHub repo for JAR downloads
 - `WINDTRADER_JAVA_STABLE_ASSET` – explicit asset URL (optional)
+- `WINDTRADER_JAVA` – explicit path to a `java` executable (or a JVM launcher) to use
+  instead of `java` on PATH. Handy on machines whose default Java is too old for the
+  target JAR — set it to a Java 21+ executable.
+- `JAVA_HOME` – if set (and `WINDTRADER_JAVA` is not), the wrapper uses
+  `<JAVA_HOME>/bin/java` as the Java executable.
+
+Java executable resolution order: `WINDTRADER_JAVA` → `JAVA_HOME/bin/java` → `java` on PATH.
 
 ---
 

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sysml-windtrader"
-version = "0.2.3"
-description = "Python wrapper around windtrader-java for SysML v2 parse-only validation."
+version = "0.2.4"
+description = "Python wrapper around windtrader-java for SysML v2 parse-only validation (requires Java 21+)."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/src/windtrader/cli.py

@@ -22,12 +22,15 @@ Exit codes (as defined by windtrader-java)
 - 0: Valid SysML (parse succeeded)
 - 2: Invalid SysML (syntax/parse error)
 - 3: Runtime error (tool failure)
-- Any other non-zero: Unexpected failure
+- Any other non-zero: mapped to 3 (runtime error)
 
 Notes
 -----
 - `--version` prints the Python package version (not the Java backend version).
 - Use `--java-version` to select which `windtrader-java` release asset to download/use.
+- The Java executable is resolved via `WINDTRADER_JAVA` (explicit path) →
+  `JAVA_HOME/bin/java` → `java` on PATH. Point `WINDTRADER_JAVA` at a Java 21+ JVM
+  if your default `java` is too old to load the default `windtrader-java` JAR.
 - `--timeout` defaults per subcommand: 10s for `check`/`echo`, 120s for `export`
   (export loads the standard library and runs resolve/transform).
 - An unknown subcommand is rejected by argparse with exit 2, the same code used

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/src/windtrader/client.py

@@ -17,14 +17,39 @@ The Python API mirrors these exactly: `validate`/`check`, `echo`, `export`.
 
 from __future__ import annotations
 
+import os
 import subprocess
 import time
 from collections.abc import Sequence
 from dataclasses import dataclass
+from pathlib import Path
 
 from ._jars import DEFAULT_VERSION, get_jar_path
 
 
+def _resolve_java() -> list[str]:
+    """
+    Return the argv prefix for the Java executable (allows an override).
+
+    Resolution order:
+    1. ``WINDTRADER_JAVA`` env var — explicit path to a ``java`` (or JVM) executable.
+    2. ``JAVA_HOME`` env var — ``<JAVA_HOME>/bin/java``.
+    3. ``java`` on PATH (default).
+
+    This lets users on a machine whose default ``java`` is too old point the wrapper
+    at a newer JVM without modifying PATH.
+    """
+    explicit = os.environ.get("WINDTRADER_JAVA", "").strip()
+    if explicit:
+        return [explicit]
+
+    java_home = os.environ.get("JAVA_HOME", "").strip()
+    if java_home:
+        return [str(Path(java_home) / "bin" / "java")]
+
+    return ["java"]
+
+
 @dataclass(frozen=True)
 class CommandResult:
     """
@@ -37,7 +62,12 @@ class CommandResult:
     version:
         windtrader-java version string used to resolve/download the jar.
     exit_code:
-        Process exit code returned by the jar.
+        Process exit code, normalized to the documented contract (0 / 2 / 3).
+        Any exit code outside (0, 2, 3) is mapped to 3 (runtime error), because a
+        JVM-level startup failure (e.g. an old JRE hitting a Java-21 jar ->
+        UnsupportedClassVersionError) returns a foreign code like 1 that would
+        otherwise break the documented 0/2/3 contract. The underlying detail is
+        preserved in `stderr`.
     stdout:
         Captured standard output from the jar.
     stderr:
@@ -56,6 +86,14 @@ class CommandResult:
     jar_path: str
     duration_s: float
 
+    def __post_init__(self) -> None:
+        # Normalize any process exit code outside the documented 0/2/3 contract to
+        # 3 (runtime error). See the `exit_code` docstring for why. Recompute `ok`
+        # from the normalized code so the two can never disagree.
+        if self.exit_code not in (0, 2, 3):
+            object.__setattr__(self, "exit_code", 3)
+        object.__setattr__(self, "ok", self.exit_code == 0)
+
     @property
     def is_invalid_syntax(self) -> bool:
         """
@@ -103,7 +141,7 @@ class WindtraderClient:
 
         t0 = time.time()
         p = subprocess.run(
-            ["java", "-jar", str(jar), subcommand],
+            [*_resolve_java(), "-jar", str(jar), subcommand],
             input=text,
             text=True,
             capture_output=True,

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/tests/test_cli.py

@@ -174,13 +174,17 @@ def test_invalid_timeout_flag_exits_with_usage_error(fake_validate, stdin_text):
 # ---------------------------------------------------------------------------
 
 
-@pytest.mark.parametrize("exit_code", [0, 2, 3, 1, 42])
-def test_forwards_jar_exit_code(fake_validate, stdin_text, exit_code):
-    """`main()` returns exactly the exit code reported by the jar."""
+@pytest.mark.parametrize("exit_code,expected", [(0, 0), (2, 2), (3, 3), (1, 3), (42, 3)])
+def test_forwards_jar_exit_code(fake_validate, stdin_text, exit_code, expected):
+    """`main()` returns the jar's exit code, normalized to the 0/2/3 contract.
+
+    Codes inside the contract (0/2/3) pass through exactly; any foreign code (e.g. 1
+    from a JVM startup failure) is mapped to 3 (runtime error).
+    """
     stdin_text("part def P;")
     fake_validate.result = _result(exit_code)
 
-    assert cli.main([]) == exit_code
+    assert cli.main([]) == expected
 
 
 def test_exit_code_is_an_int(fake_validate, stdin_text):

{sysml_windtrader-0.2.3 → sysml_windtrader-0.2.4}/tests/test_client.py

@@ -110,13 +110,25 @@ def test_parse_error_result_flags():
     assert res.is_runtime_error is False
 
 
-@pytest.mark.parametrize("exit_code", [1, 3, 127, -9])
-def test_runtime_error_result_flags(exit_code):
-    """Any exit code outside (0, 2) is surfaced as a runtime/tool error."""
+@pytest.mark.parametrize("exit_code", [1, 127, -9, 42, 137])
+def test_runtime_error_result_flags_normalized(exit_code):
+    """Any exit code outside (0, 2, 3) surfaces as is_runtime_error AND is normalized to 3."""
     res = _result(exit_code)
     assert res.ok is False
     assert res.is_invalid_syntax is False
     assert res.is_runtime_error is True
+    # Normalization keeps the documented 0/2/3 contract (regression: a JVM startup
+    # failure like an old JRE hitting a Java-21 jar leaks code 1).
+    assert res.exit_code == 3
+
+
+def test_exit_code_3_is_runtime_error_not_normalized():
+    """3 is already inside the contract and stays 3."""
+    res = _result(3)
+    assert res.exit_code == 3
+    assert res.ok is False
+    assert res.is_runtime_error is True
+    assert res.is_invalid_syntax is False
 
 
 def test_validation_result_is_frozen():
@@ -132,12 +144,58 @@ def test_validation_result_is_frozen():
 
 
 def test_validate_text_builds_exact_check_argv(fake_run):
-    """`check` is invoked as exactly [\"java\", \"-jar\", <jar>, \"check\"]."""
+    """`check` is invoked as exactly [\"java\", \"-jar\", <jar>, \"check\"] by default."""
     WindtraderClient().validate_text("part { attribute mass; }")
 
     assert fake_run.argv == ["java", "-jar", str(FAKE_JAR), "check"]
 
 
+def test_java_executable_resolution_defaults_to_java(fake_run, monkeypatch):
+    """With no WINDTRADER_JAVA / JAVA_HOME, the argv prefix is plain `java`."""
+    monkeypatch.delenv("WINDTRADER_JAVA", raising=False)
+    monkeypatch.delenv("JAVA_HOME", raising=False)
+
+    WindtraderClient().validate_text("part def P;")
+    assert fake_run.argv[0] == "java"
+
+
+def test_java_executable_resolution_uses_java_home(fake_run, monkeypatch):
+    """`JAVA_HOME` is used as `<JAVA_HOME>/bin/java` when WINDTRADER_JAVA is absent."""
+    monkeypatch.delenv("WINDTRADER_JAVA", raising=False)
+    monkeypatch.setenv("JAVA_HOME", "/opt/jdk21")
+
+    WindtraderClient().validate_text("part def P;")
+    assert fake_run.argv[0] == "/opt/jdk21/bin/java"
+
+
+def test_java_executable_resolution_prefers_windtrader_java(fake_run, monkeypatch):
+    """`WINDTRADER_JAVA` (explicit path) wins over JAVA_HOME."""
+    monkeypatch.setenv("WINDTRADER_JAVA", "/custom/bin/java21")
+    monkeypatch.setenv("JAVA_HOME", "/opt/jdk-not-used")
+
+    WindtraderClient().validate_text("part def P;")
+    assert fake_run.argv[0] == "/custom/bin/java21"
+
+
+def test_jvm_startup_failure_normalized_and_stderr_preserved(fake_run):
+    """A JVM startup failure (rc=1, e.g. old Java vs Java-21 jar) -> 3, stderr kept."""
+    fake_run.returncode = 1
+    fake_run.stdout = ""
+    fake_run.stderr = (
+        "Error: LinkageError occurred while loading main class "
+        "io.westfall.windtrader.RoundTrip\n\tjava.lang.UnsupportedClassVersionError: "
+        "class file version 65.0 ... only recognizes class file versions up to 62.0"
+    )
+
+    res = WindtraderClient().validate_text("part { attribute mass; }")
+
+    assert res.exit_code == 3
+    assert res.is_runtime_error is True
+    assert res.is_invalid_syntax is False
+    assert res.ok is False
+    assert "UnsupportedClassVersionError" in res.stderr
+
+
 def test_echo_builds_exact_echo_argv(fake_run):
     """`echo` is invoked as exactly [\"java\", \"-jar\", <jar>, \"echo\"]."""
     WindtraderClient().echo("part { attribute mass; }")