Skip to content

Commit c7bbc22

Browse files
committed
fix: Address review on the PATH host-format change
Four findings from the automated review. Three were correct, one was not. **Correct.** The comment claiming this is "idempotent for a value a rule did match" overclaimed. It holds for a POSIX- or WINDOWS-format rule, whose output `apply` rebuilds through `PureWindowsPath`, but not for a URI-format rule: `_apply_uri` copies `destination_path` verbatim and uses the host separator only for the appended child parts. Measured, a URI rule with a POSIX-spelled destination on a Windows host gives `/tmp/openjd\scene\out` from `apply` alone, which this then completes to `\tmp\openjd\scene\out`. That is a real behaviour change on a matched rule and no test covered it. It is also exactly what openjd-rs produces for the same mapped string, measured through `new_path(mapped, host())`, so completing it is the intent rather than a side effect. The comment now states both cases and `test_a_matching_uri_rule_is_completed_not_left_mixed` pins them, asserting the `apply`-only value first so a future change to `_apply_uri` says which half moved. **Correct.** Two maintainability points: `to_host_path_separators` was defined above the `_URI_SOURCE_RE` it reads, which worked only because the global is resolved at call time; it now follows the regex. And the test module's docstring named a `host_path_format` that never shipped -- an earlier name for this function -- so a reader following it found nothing. **Not an error.** The review flagged `_URI_SOURCE_RE`'s one-character scheme as misclassifying a Windows drive letter, since `C://Users/foo` is treated as a URI and returned unchanged while `C:/Users/foo` is converted, and asked whether openjd-rs guards against a one-character scheme. It does not. Measured through the engine, openjd-rs renders `C://Users/foo`, `C:/Users/foo`, `x://y/z` and four other cases identically to this function -- 7/7 agreement. RFC 3986 §3.1 admits a single-character scheme and the Expression Language states the pattern as `^[a-zA-Z][a-zA-Z0-9+.-]*://`, so this is the specified behaviour, and tightening the regex would make this package diverge from the implementation it is being aligned with. Pinned deliberately by `test_a_one_character_scheme_matches_the_engine` so it is not later "fixed" into a divergence; if the behaviour is wrong it is wrong in the specification. Also, per review feedback, the three branches now carry the openjd-expr source they were transcribed from -- `normalize_path_separators` in `crates/openjd-expr/src/value.rs` -- quoted inline so the copy can be diffed against the original without leaving the file. `normalize_path_separators` and the `uri_path::parse` behind its `is_uri` are byte identical in openjd-expr 0.5.0 and 0.6.0, checked against both crates.io sources rather than assumed. No production logic changed: the diff is one moved function, comments, and tests. 21 tests now (was 17), all 7 mutants still caught, and the full suite is unchanged at the same 8 pre-existing environmental failures with 1007 passing (was 1003). Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>
1 parent 9cd6b77 commit c7bbc22

3 files changed

Lines changed: 131 additions & 17 deletions

File tree

‎src/openjd/sessions/_path_mapping.py‎

Lines changed: 40 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,14 @@ def _ascii_lower(value: str) -> str:
2626
return value.translate(_ASCII_LOWER_TABLE)
2727

2828

29+
_URI_SOURCE_RE = re.compile(r"[A-Za-z][A-Za-z0-9+.\-]*://")
30+
"""A URI-format rule's ``source_path`` must start with ``<scheme>://``.
31+
32+
Mirrors the scheme grammar of RFC 3986 §3.1, which is what the EXPR engine's
33+
URI parser accepts. Validated in the constructor so a malformed rule is rejected
34+
where the value can be named."""
35+
36+
2937
def to_host_path_separators(value: str) -> str:
3038
"""Render ``value`` with this host's path separators.
3139
@@ -53,22 +61,46 @@ def to_host_path_separators(value: str) -> str:
5361
the non-EXPR path. The URI test reuses :data:`_URI_SOURCE_RE`, which is this
5462
module's existing spelling of the same ``<scheme>://`` rule, so the
5563
duplication is of Rust's three-way branch only.
64+
65+
Note that a one-character scheme is a URI to both implementations, so
66+
``C://Users/foo`` keeps its forward slashes while ``C:/Users/foo`` does not.
67+
That looks like a drive-letter misclassification and is deliberate: RFC 3986
68+
§3.1 admits a single-character scheme, ``openjd-rs``'s ``uri_path::is_uri``
69+
accepts one, and the Expression Language's stated pattern
70+
(``^[a-zA-Z][a-zA-Z0-9+.-]*://``) does too. Measured against the engine, the
71+
two agree on this input and on ``x://y/z``. Tightening the regex here would
72+
make this package diverge from the oracle it is being aligned with, so if the
73+
behaviour is wrong it is wrong in the specification.
5674
"""
75+
# The three branches below are a transcription of openjd-expr's
76+
# `normalize_path_separators`, in `crates/openjd-expr/src/value.rs`. Kept in
77+
# the same order as the original so the two can be diffed by eye. Quoted here
78+
# from openjd-expr 0.6.0; `openjd-model`'s `rust-bindings` links 0.5.0, and
79+
# this function and the `uri_path::parse` behind its `is_uri` are byte
80+
# identical in both (checked against the two crates.io sources, not assumed):
81+
#
82+
# pub fn normalize_path_separators(value: &str, format: PathFormat) -> String {
83+
# if crate::uri_path::is_uri(value) {
84+
# return value.to_string();
85+
# }
86+
# match format {
87+
# PathFormat::Windows => value.replace('/', "\\"),
88+
# PathFormat::Posix | PathFormat::Uri => value.to_string(),
89+
# }
90+
# }
91+
#
92+
# `format` is always the host's here, so the `Uri` arm of that `match` is
93+
# unreachable from this caller and is folded into the POSIX one. If you change
94+
# anything below, check it against that function first -- the whole reason this
95+
# is a copy rather than a call is in the docstring, and a silent divergence is
96+
# the cost that buys.
5797
if _URI_SOURCE_RE.match(value) is not None:
5898
return value
5999
if os_name == "posix":
60100
return value
61101
return value.replace("/", "\\")
62102

63103

64-
_URI_SOURCE_RE = re.compile(r"[A-Za-z][A-Za-z0-9+.\-]*://")
65-
"""A URI-format rule's ``source_path`` must start with ``<scheme>://``.
66-
67-
Mirrors the scheme grammar of RFC 3986 §3.1, which is what the EXPR engine's
68-
URI parser accepts. Validated in the constructor so a malformed rule is rejected
69-
where the value can be named."""
70-
71-
72104
class PathFormat(str, Enum):
73105
POSIX = "POSIX"
74106
WINDOWS = "WINDOWS"

‎src/openjd/sessions/_session.py‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1677,8 +1677,18 @@ def processed_parameter_value(param: ParameterValue) -> Any:
16771677
# submitter wrote it, and on a Windows host a POSIX-spelled
16781678
# parameter stayed POSIX-spelled. openjd-rs wraps both the mapped
16791679
# and the unmapped case in `ExprValue::new_path(.., host())`.
1680-
# Applying it after `apply_mapping` is idempotent for a value a rule
1681-
# did match, which is what keeps the two paths agreeing.
1680+
#
1681+
# For a POSIX- or WINDOWS-format rule this is idempotent, because
1682+
# `apply` rebuilds the result through `PureWindowsPath` and leaves no
1683+
# forward slash to replace. For a URI-format rule it is not:
1684+
# `_apply_uri` copies `destination_path` verbatim and uses the host
1685+
# separator only for the appended child parts, so a POSIX-spelled
1686+
# destination on a Windows host yields a mixed result
1687+
# ("/tmp/openjd\\scene\\out") that this then completes
1688+
# ("\\tmp\\openjd\\scene\\out"). That is the openjd-rs answer for the
1689+
# same input -- measured -- so completing it is the point rather than
1690+
# a side effect. `TestPathParameterFormatAndPathMappingAgree` pins
1691+
# both cases.
16821692
if param.type == ParameterValueType.PATH:
16831693
return to_host_path_separators(apply_mapping(param.value))
16841694
if param.type == ParameterValueType.LIST_PATH and isinstance(param.value, list):

‎test/openjd/sessions_v0/test_path_parameter_host_format.py‎

Lines changed: 79 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,12 @@
2929
is deliberate rather than a simplification: that module-level name is the single
3030
place this package decides which separator a host-scope path uses. It is what
3131
``PathMappingRule.apply`` reads for the separator of a rule's output, and it is
32-
what ``host_path_format`` reads for the format of an unmapped value. Patching one
33-
and not the other would produce a self-inconsistent host -- mapped values
34-
rendering Windows while unmapped ones rendered POSIX -- and a test built on that
35-
would assert an arrangement that cannot occur in production. Keeping both readers
36-
on one seam is the reason the fix put ``host_path_format`` in ``_path_mapping``
37-
rather than deriving ``os.name`` a second time in ``_session``.
32+
what ``to_host_path_separators`` reads for the format of an unmapped value.
33+
Patching one and not the other would produce a self-inconsistent host -- mapped
34+
values rendering Windows while unmapped ones rendered POSIX -- and a test built on
35+
that would assert an arrangement that cannot occur in production. Keeping both
36+
readers on one seam is the reason the fix put ``to_host_path_separators`` in
37+
``_path_mapping`` rather than deriving ``os.name`` a second time in ``_session``.
3838
"""
3939

4040
from __future__ import annotations
@@ -93,7 +93,11 @@ def _symtab(
9393

9494

9595
def _path_param(value: str) -> dict[str, ParameterValue]:
96-
return {"InputFile": ParameterValue(type=ParameterValueType.PATH, value=value)}
96+
return _path_param_named("InputFile", value)
97+
98+
99+
def _path_param_named(name: str, value: str) -> dict[str, ParameterValue]:
100+
return {name: ParameterValue(type=ParameterValueType.PATH, value=value)}
97101

98102

99103
# ---------------------------------------------------------------------------
@@ -179,6 +183,45 @@ def test_a_matching_rule_is_unchanged_by_the_fix(self) -> None:
179183
# THEN the mapped value is what path mapping produced, unaltered
180184
assert str(symtab["Task.Param.InputFile"]) == r"C:\dest\a.exr"
181185

186+
def test_a_matching_uri_rule_is_completed_not_left_mixed(self) -> None:
187+
"""A URI-format rule is the one case where this is *not* a no-op, and
188+
that is deliberate.
189+
190+
``PathMappingRule._apply_uri`` copies ``destination_path`` verbatim and
191+
uses the host separator only for the appended child parts, so a
192+
POSIX-spelled destination on a Windows host comes out of ``apply``
193+
half-converted -- ``/tmp/openjd\\scene\\out``. openjd-rs wraps the mapped
194+
value in ``new_path(mapped, host())`` regardless of the rule's format, and
195+
measured against the engine that yields the fully converted form. So
196+
completing it here is agreement with the oracle, not a side effect.
197+
198+
The `apply`-only value is asserted first, so if `_apply_uri` ever starts
199+
emitting host separators for the whole path this test says which half
200+
changed instead of just failing.
201+
"""
202+
# GIVEN a URI-format rule with a POSIX-spelled destination, which is how
203+
# the existing suite spells cross-format rules
204+
rules = [
205+
PathMappingRule(
206+
source_path_format=PathFormat.URI,
207+
source_path="s3://bucket/prefix",
208+
destination_path=PurePosixPath("/tmp/openjd"),
209+
)
210+
]
211+
given = "s3://bucket/prefix/scene/out"
212+
213+
# WHEN the rule is applied on a Windows host, and again through the table
214+
with _host("nt"):
215+
matched, mapped_only = rules[0].apply(path=given)
216+
symtab = _symtab(_path_param_named("InputFile", given), os_name="nt", rules=rules)
217+
218+
# THEN path mapping alone leaves a mixed-separator result
219+
assert matched is True
220+
assert mapped_only == "/tmp/openjd\\scene\\out"
221+
222+
# AND the symbol table completes it to the host's format
223+
assert str(symtab["Task.Param.InputFile"]) == r"\tmp\openjd\scene\out"
224+
182225

183226
class TestPathParameterFormatIsSeparatorsOnly:
184227
"""Guards the *shape* of the conversion. Rendering through
@@ -207,6 +250,35 @@ def test_windows_host_replaces_separators_only(self, given: str, expected: str)
207250
# THEN only the separators changed
208251
assert str(symtab["Task.Param.InputFile"]) == expected
209252

253+
@pytest.mark.parametrize(
254+
"given,expected",
255+
[
256+
pytest.param("C://Users/foo", "C://Users/foo", id="one-char scheme is a URI"),
257+
pytest.param("C:/Users/foo", r"C:\Users\foo", id="drive letter is not a URI"),
258+
pytest.param("x://y/z", "x://y/z", id="one-char scheme, non-drive letter"),
259+
],
260+
)
261+
def test_a_one_character_scheme_matches_the_engine(self, given: str, expected: str) -> None:
262+
"""``C://Users/foo`` keeps its forward slashes and ``C:/Users/foo`` does
263+
not. That reads like a drive-letter misclassification; it is what the
264+
oracle does.
265+
266+
RFC 3986 §3.1 admits a single-character scheme, the Expression Language's
267+
stated pattern is ``^[a-zA-Z][a-zA-Z0-9+.-]*://``, and openjd-rs's
268+
``uri_path::is_uri`` accepts one -- measured through the engine, it renders
269+
all three of these identically to the assertions below. So this is pinned
270+
deliberately: tightening the regex to require two scheme characters would
271+
make this package diverge from the implementation it is being aligned
272+
with. If the behaviour is wrong, it is wrong in the specification, and
273+
this test should change when the specification does.
274+
"""
275+
# GIVEN a value whose scheme is one character
276+
# WHEN the table is built on a Windows host
277+
symtab = _symtab(_path_param(given), os_name="nt")
278+
279+
# THEN it is treated exactly as the engine treats it
280+
assert str(symtab["Task.Param.InputFile"]) == expected
281+
210282
def test_a_uri_is_left_alone(self) -> None:
211283
"""A ``path`` holding a URI keeps forward slashes on every host. The
212284
Expression Language spec makes URI paths exempt from the host's

0 commit comments

Comments
 (0)