vis-agent 0.2.35.dev7414__tar.gz → 0.2.37.dev7443__tar.gz

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.2.35.dev7414
+Version: 0.2.37.dev7443
 Summary: The Vis Python SDK — author extensions and control local or remote engines.
 Project-URL: Homepage, https://vis.blockether.com
 Project-URL: Documentation, https://vis.blockether.com

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/contracts/schema/toggle.json

@@ -46,7 +46,7 @@
         "description": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 100,
+          "maxLength": 300,
           "pattern": "^[^\\r\\n]+$"
         },
         "default": {},

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vis-agent"
-version = "0.2.35.dev7414"
+version = "0.2.37.dev7443"
 description = "The Vis Python SDK — author extensions and control local or remote engines."
 readme = "README.md"
 requires-python = ">=3.11"

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/src/blockether/vis/_contracts.py

@@ -74,16 +74,62 @@ def _json_value(item):
     )
 
 
+def _problem(error) -> str:
+    """One readable line for a schema error: field, rule and limit, never the value."""
+    field = ".".join(str(part) for part in error.absolute_path) or "declaration"
+    rule, limit = error.validator, error.validator_value
+    if rule in ("maxLength", "minLength"):
+        bound = "maximum" if rule == "maxLength" else "minimum"
+        fix = f" Shorten the {field}." if rule == "maxLength" else ""
+        return (
+            f"{field} is {len(error.instance)} characters; {bound} is {limit} ({rule})."
+            + fix
+        )
+    if rule == "required":
+        missing = ", ".join(key for key in limit if key not in error.instance)
+        return f"{missing} is missing (required)."
+    if rule == "enum":
+        return f"{field} must be one of: {', '.join(map(str, limit))} (enum)."
+    if rule == "pattern":
+        if (
+            limit
+            == definition("toggle", "contribution")["properties"]["description"][
+                "pattern"
+            ]
+        ):
+            return f"{field} must be one line without line breaks (pattern)."
+        return f"{field} does not match the pattern {limit} (pattern)."
+    return f"{field} breaks the {rule} rule."
+
+
+def problems(name: str, definition: str, value: Any) -> list[str]:
+    """Readable rule failures of `value`, one line for each. Empty when it is valid.
+
+    Each line names the field, the rule and its limit. It never echoes the value.
+    """
+    if not _json_value(value):
+        return ["the value is not JSON data."]
+    errors = _validator(name, definition).iter_errors(value)
+    return [
+        _problem(error)
+        for error in sorted(errors, key=lambda e: list(map(str, e.absolute_path)))
+    ]
+
+
 def validate(name: str, definition: str, value: Any) -> Any:
     """Validate portable JSON data, returning it or raising a payload-free ValueError.
 
-    Schemas resolve only from the installed package. Runtime lifecycle, IO and
+    The error names each failed field, rule and limit, never the value. Schemas
+    resolve only from the installed package. Runtime lifecycle, IO and
     authorization belong to the engine, not JSON Schema.
     """
     try:
-        valid = _json_value(value) and _validator(name, definition).is_valid(value)
+        found = problems(name, definition, value)
     except (RecursionError, TypeError, ValueError):
-        valid = False
-    if not valid:
-        raise ValueError(f"invalid {name}.{definition} contract")
+        found = [""]
+    if found:
+        detail = " ".join(problem for problem in found if problem)
+        raise ValueError(
+            f"invalid {name}.{definition} contract" + (f": {detail}" if detail else "")
+        )
     return value

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/src/blockether/vis/_outside.py

@@ -91,13 +91,20 @@ def workspace_root():
 
 def setting_declaration(spec):
     """Use the package's own JSON Schemas for outside-host declarations."""
-    from ._contracts import definition, validate
+    from ._contracts import definition, problems, validate
 
     spec = dict(spec)
     spec.setdefault(
         "scopes",
         definition("toggle", "contribution")["properties"]["scopes"]["default"],
     )
+    found = problems("toggle", "contribution", spec)
+    if found:
+        name = spec.get("id")
+        label = (
+            f"Invalid setting {name}" if isinstance(name, str) else "Invalid setting"
+        )
+        raise ValueError(f"{label}: {' '.join(found)}")
     return validate("toggle", "contribution", spec)
 
 

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/src/blockether/vis/extension.py

@@ -1388,10 +1388,11 @@ def _call_arguments(fn, args, kwargs):
     An argument crosses the host boundary as JSON, so a record arrives as a dict of its
     public fields. A parameter annotated with a dataclass gets that dataclass back,
     built through its constructor. This also works inside a union, list, tuple, set or
-    dict annotation (Blockether/vis#289). Annotations resolve statically, as for tool
-    contracts. A value that does not fit its annotation stays as it arrived. So does
-    every argument of a call that the signature cannot bind: the call itself reports
-    that mistake.
+    dict annotation (Blockether/vis#289). One bare string for a sequence of strings
+    becomes one item, not one item for each character (Blockether/vis#324).
+    Annotations resolve statically, as for tool contracts. A value that does not fit
+    its annotation stays as it arrived. So does every argument of a call that the
+    signature cannot bind: the call itself reports that mistake.
     """
     try:
         # A wrapper around a bound method must not unwrap past the binding.
@@ -1561,9 +1562,10 @@ def _holds_record(shape):
 def _rebuilt_value(shape, value):
     """Return `value` with the records that `shape` expects rebuilt.
 
+    One bare string for a sequence of strings becomes that sequence with one item.
     A value that does not fit stays as is.
     """
-    if not _holds_record(shape):
+    if not (_holds_record(shape) or isinstance(value, str)):
         return value
     result = _fitted_argument(shape, value)
     return value if result is _UNFIT else result
@@ -1588,7 +1590,11 @@ def _fitted_argument(shape, value):
     if kind == "record":
         return _rebuilt_record(shape[1], value, shape[2])
     if kind == "union":
-        for member in shape[1]:
+        members = shape[1]
+        if isinstance(value, str):
+            # A member that takes the string as it is wins over one that wraps it.
+            members = sorted(members, key=lambda member: member[0] == "sequence")
+        for member in members:
             result = _fitted_argument(member, value)
             if result is not _UNFIT:
                 return result
@@ -1599,6 +1605,13 @@ def _fitted_argument(shape, value):
         if not _holds_record(shape):
             return value
         return {key: _rebuilt_value(shape[1], item) for key, item in value.items()}
+    if kind == "sequence" and isinstance(value, str):
+        # A string is a sequence of its characters; the caller named one item. An
+        # item of any type also takes the whole string, so it stays as it is.
+        if shape[2] in (("any",), ("plain", object)):
+            return _UNFIT
+        item = _fitted_argument(shape[2], value)
+        return _UNFIT if item is _UNFIT else shape[1]((item,))
     if not isinstance(value, (list, tuple)):
         return _UNFIT
     if kind == "fixed":

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/tests/test_contracts.py

@@ -178,6 +178,12 @@ def test_payload_free_validation():
         with pytest.raises(ValueError) as error:
             _contracts.validate("activity", "declaration", bad)
         assert "do-not-echo" not in str(error.value)
+    with pytest.raises(
+        ValueError, match=r": label does not match the pattern .* \(pattern\)"
+    ):
+        _contracts.validate(
+            "activity", "declaration", {"presenter": "tests", "label": "one\ntwo"}
+        )
     with pytest.raises(ValueError):
         _contracts.validate("view", "missing-definition", {})
 

{vis_agent-0.2.35.dev7414 → vis_agent-0.2.37.dev7443}/tests/test_scoped_settings.py

@@ -68,6 +68,32 @@ def test_parent_nests_a_setting():
         vis.Setting(id="test_detail", label="Test detail", default=False, parent=" ")
 
 
+# Regression for #322 and #323: a 300-character description is valid, and a
+# longer one names the setting, the field, the rule and the limit.
+def test_description_limit_and_actionable_error():
+    def mode(description):
+        return vis.Setting(
+            id="steering_mode",
+            label="Steering mode",
+            type="enum",
+            choices=["vibe", "control"],
+            default="vibe",
+            description=description,
+        )
+
+    assert mode("x" * 300).description == "x" * 300
+    with pytest.raises(ValueError) as error:
+        mode("x" * 301)
+    assert str(error.value) == (
+        "Invalid setting steering_mode: description is 301 characters; "
+        "maximum is 300 (maxLength). Shorten the description."
+    )
+    with pytest.raises(ValueError, match="one line without line breaks"):
+        mode("two\nlines")
+    with pytest.raises(ValueError, match="minimum is 1"):
+        mode("")
+
+
 def test_application_bridge_rejects_host_only_settings_before_connecting():
     declaration = vis.Extension(
         name="Settings test",

vis_agent-0.2.37.dev7443/tests/test_text_list_arguments.py

@@ -0,0 +1,89 @@
+"""Regression coverage for #324: one bare string for a list of strings is one item."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Annotated, Literal, Optional
+
+import blockether.vis.extension as vis
+
+
+class Tools:
+    """The parameter shapes of the `py.*` and `clj.*` language tools."""
+
+    def lint_code(
+        self,
+        paths: Annotated[Sequence[str], "Files or directories to lint."] = (),
+        *,
+        cwd: str = "",
+        namespaces: Annotated[Sequence[str], "Test namespaces to run."] = (),
+    ) -> tuple:
+        return tuple(paths), tuple(namespaces)
+
+
+def rebuilt(fn, *args, **kwargs):
+    return vis._call_arguments(fn, list(args), kwargs)
+
+
+def test_bare_string_for_a_string_sequence_is_one_item():
+    # Regression for Blockether/vis#324: `py.lint_code("/src/app.py")` named one
+    # path for each character, and `/` made the lint walk the whole filesystem.
+    tools = Tools()
+    args, kwargs = rebuilt(tools.lint_code, "/src/app.py", namespaces="my.ns-test")
+    assert args == [["/src/app.py"]]
+    assert kwargs == {"namespaces": ["my.ns-test"]}
+    assert tools.lint_code(*args, **kwargs) == (("/src/app.py",), ("my.ns-test",))
+    assert rebuilt(tools.lint_code, paths="a.py")[1] == {"paths": ["a.py"]}
+
+
+def test_lists_and_other_parameters_stay_as_they_arrived():
+    tools = Tools()
+    paths = ["a.py", "b.py"]
+    args, kwargs = rebuilt(tools.lint_code, paths, cwd="/src")
+    assert args[0] is paths
+    assert kwargs == {"cwd": "/src"}
+
+
+def test_container_and_item_annotations_decide_the_shape():
+    def files(
+        paths: list[str], tags: set[str] = frozenset(), pair: tuple[str, ...] = ()
+    ):
+        return paths, tags, pair
+
+    def optional(paths: Optional[list[str]] = None, more: list[str] | None = None):  # noqa: UP045
+        return paths, more
+
+    def literal(modes: list[Literal["fast", "full"]] = ()):
+        return modes
+
+    assert rebuilt(files, "a.py", tags="x", pair="y") == (
+        [["a.py"]],
+        {"tags": {"x"}, "pair": ("y",)},
+    )
+    assert rebuilt(optional, "a.py", more="b.py") == ([["a.py"]], {"more": ["b.py"]})
+    assert rebuilt(literal, "fast") == ([["fast"]], {})
+    assert rebuilt(literal, "other") == (["other"], {})
+
+
+def test_a_member_that_takes_the_string_as_it_is_wins():
+    def either(paths: list[str] | str = (), path: str | list[str] = ""):
+        return paths, path
+
+    def anything(
+        values: list = (), items: Sequence[object] = (), raw: list[bytes] = ()
+    ):
+        return values, items, raw
+
+    assert rebuilt(either, "a.py", path="b.py") == (["a.py"], {"path": "b.py"})
+    assert rebuilt(anything, "ab", items="cd", raw="ef") == (
+        ["ab"],
+        {"items": "cd", "raw": "ef"},
+    )
+
+
+def test_path_items_take_a_bare_string_unchanged():
+    def walk(paths: list[str | Path] = ()):
+        return paths
+
+    assert rebuilt(walk, "src") == ([["src"]], {})