Files
chenlin c32df70326
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

237 lines
9.9 KiB
Python

"""`deploy/app.schema`: what a bundle is, held to the bundles that are built.
A schema that nothing checks describes what the bundler did once. So every
build is held to it (`deploy.validate_app`, before the `.app` is packed), and
this pins that the check refuses each way a bundle can depart from it -- with a
bundle small enough to write by hand as the control group, which has to pass.
The manual's translation goes through the same gate: `--translate` compares
every identifier against the English, so a Chinese manual that moved a key is
refused rather than shipped as a manual for another bundle.
No toolchain: this writes a bundle by hand, so it runs on a machine that only
trains. The newest bundle actually built on this machine is checked too, when
there is one.
"""
from __future__ import annotations
import copy
import importlib.util
from importlib.resources import files
import json
import re
import zipfile
from pathlib import Path
import pytest
REPO = Path(__file__).resolve().parents[1]
SCRIPT = REPO / "scripts/deploy.py"
SCHEMA = REPO / "deploy/app.schema"
def test_runtime_schema_matches_the_published_schema() -> None:
assert files("mjrl.platform").joinpath("app.schema").read_bytes() == SCHEMA.read_bytes()
def test_runtime_license_matches_the_platform_license() -> None:
assert files("mjrl.platform").joinpath("LICENSE").read_bytes() == (REPO / "LICENSE").read_bytes()
def deploy():
"""`scripts/deploy.py` as a module, by path; see `test_bundle_archive.py`."""
spec = importlib.util.spec_from_file_location("deploy_for_schema", SCRIPT)
assert spec and spec.loader
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
MANUAL = {
"schema": "kk-bundle-manual/1",
"language": "en",
"bundle": "tiny",
"source": "Generated by scripts/deploy.py.",
"modes": [{
"mode": "walk", "task": "example_robot.posture", "default": True,
"summary": "The mode the robot starts in.",
"enter": "Where the robot starts.",
"leave": "Leaving it is switching to another mode.",
"keyboard": "A key held pushes what it drives further the longer it is held.",
"controls": [{"control": "Ly", "pad": "left stick, up and down",
"does": "up: walk forward; down: walk back"}],
"keys": [{"key": "W", "does": "walk forward"},
{"key": "S", "does": "walk back"}],
}],
"switches": [{"device": "pad", "control": "A", "with": None, "keys": [], "pad": "A",
"does": "switch to walk; press again to switch back", "from": None},
{"device": "keyboard", "control": "key_space", "with": None, "keys": ["Space"],
"pad": None, "does": "switch to walk; press again to switch back",
"from": ["walk"]}],
}
def write_bundle(out: Path) -> Path:
"""The smallest bundle the schema describes, with a correct `bundle.json`."""
d = deploy()
files = {
"README.md": "# tiny\n",
"controller.toml": "[fsm]\n",
"walk.json": "{}\n",
"models/walk.onnx": "not a model",
"runtime/web/controller.js": "// glue\n",
"runtime/web/controller.wasm": "\0asm",
"manual.en.json": json.dumps(MANUAL, ensure_ascii=False),
}
for name, text in files.items():
(out / name).parent.mkdir(parents=True, exist_ok=True)
(out / name).write_text(text, "utf-8")
manifest = {
"schema": "kk-policy-bundle/1",
"runtimes": {"web": {"model": "onnx", "glue": "runtime/web/controller.js",
"wasm": "runtime/web/controller.wasm", "commit": "abc",
"unverifiedByTheConsumer": "say so"}},
"fsm": "controller.toml",
"modes": {"walk": {"models": {"onnx": "models/walk.onnx"}, "contract": "walk.json",
"observation": 3, "action": 2}},
"notes": [],
"reference": None,
"manuals": {"en": "manual.en.json"},
"files": {name: {"bytes": (out / name).stat().st_size, "sha256": d.sha256(out / name)}
for name in sorted(files)},
}
(out / "bundle.json").write_text(json.dumps(manifest, indent=2), "utf-8")
return out
@pytest.fixture
def bundle(tmp_path: Path) -> Path:
return write_bundle(tmp_path / "tiny")
def test_the_schema_is_a_schema() -> None:
"""A malformed schema validates nothing, and says so to nobody."""
import jsonschema
schema = json.loads(SCHEMA.read_text("utf-8"))
jsonschema.Draft202012Validator.check_schema(schema)
for rule in schema["x-files"]:
assert {"path", "required", "format", "is"} <= set(rule), rule
re.compile(rule["path"])
def test_a_bundle_the_schema_describes_passes(bundle: Path) -> None:
"""The control group: every refusal below would pass against a check that
refuses everything."""
deploy().validate_app(bundle)
def _mutations():
def stray(b: Path):
(b / "notes.txt").write_text("hello", "utf-8")
def no_manual(b: Path):
(b / "manual.en.json").unlink()
def manifest(edit):
def apply(b: Path):
m = json.loads((b / "bundle.json").read_text("utf-8"))
edit(m)
(b / "bundle.json").write_text(json.dumps(m), "utf-8")
return apply
def manual(edit):
def apply(b: Path):
m = copy.deepcopy(MANUAL)
edit(m)
(b / "manual.en.json").write_text(json.dumps(m), "utf-8")
manifest(lambda x: x["files"]["manual.en.json"].update(
bytes=(b / "manual.en.json").stat().st_size,
sha256=deploy().sha256(b / "manual.en.json")))(b)
return apply
return [
("a file no bundle holds", stray, "no file of this name belongs"),
("no manual", no_manual, "missing: a file matching ^manual"),
("no runtimes", manifest(lambda m: m.pop("runtimes")), "'runtimes' is a required"),
("a mode with one model", manifest(lambda m: m["modes"]["walk"].update(
model=m["modes"]["walk"].pop("models"))), "'models' is a required"),
("a listed file that is not there", manifest(lambda m: m["files"].update(
{"gone.json": {"bytes": 1, "sha256": "0" * 64}})), "not on disk"),
("a manual mode that says nothing of entering it", manual(
lambda m: m["modes"][0].pop("enter")), "'enter' is a required"),
("a target the host keys it by", manifest(lambda m: m.update(target="web")),
"Additional properties"),
]
@pytest.mark.parametrize("why,mutate,message", _mutations(), ids=[m[0] for m in _mutations()])
def test_each_departure_from_the_schema_is_refused(bundle: Path, why, mutate, message) -> None:
mutate(bundle)
with pytest.raises(SystemExit) as raised:
deploy().validate_app(bundle)
assert message in str(raised.value), str(raised.value)
def chinese() -> dict:
zh = copy.deepcopy(MANUAL)
zh["language"] = "zh"
zh["source"] = "由 scripts/deploy.py 生成。"
mode = zh["modes"][0]
mode.update(summary="机器人开机所在的模式。", enter="开机即是。", leave="切换到别的模式即离开。",
keyboard="按住一个键,摇杆推得越久越满。")
mode["controls"][0].update(pad="左摇杆上下", does="上:前进;下:后退")
mode["keys"][0]["does"] = "前进"
mode["keys"][1]["does"] = "后退"
zh["switches"][0].update(pad="A", does="进入 walk;再按一次退出")
zh["switches"][1].update(does="进入 walk;再按一次退出")
return zh
def test_a_translation_goes_in_and_the_app_is_packed_again(bundle: Path, tmp_path: Path) -> None:
source = tmp_path / "manual.zh.json"
source.write_text(json.dumps(chinese(), ensure_ascii=False), "utf-8")
assert deploy().translate(bundle, "zh", source) == 0
manifest = json.loads((bundle / "bundle.json").read_text("utf-8"))
assert manifest["manuals"] == {"en": "manual.en.json", "zh": "manual.zh.json"}
raw = (bundle / "manual.zh.json").read_bytes()
assert manifest["files"]["manual.zh.json"]["bytes"] == len(raw)
# The archive carries it, so a consumer handed the `.app` has it too.
with zipfile.ZipFile(bundle.with_suffix(".app")) as bag:
assert json.loads(bag.read("manual.zh.json"))["language"] == "zh"
@pytest.mark.parametrize("edit,message", [
(lambda zh: zh["modes"][0]["keys"][0].update(key="Z"), "changes more than"),
(lambda zh: zh["switches"][1].update(keys=["空格"]), "changes more than"),
(lambda zh: zh["switches"][1].update(**{"from": ["jump"]}), "changes more than"),
(lambda zh: zh["modes"].append(copy.deepcopy(zh["modes"][0])), "changes more than"),
(lambda zh: zh.update(language="ja"), "says language 'ja'"),
])
def test_a_translation_that_changes_more_than_the_text_is_refused(
bundle: Path, tmp_path: Path, edit, message) -> None:
"""A key moved, a key cap translated, a mode added: each is a manual for
another bundle. The control group is the test above, the same translation
with only its text changed."""
zh = chinese()
edit(zh)
source = tmp_path / "manual.zh.json"
source.write_text(json.dumps(zh, ensure_ascii=False), "utf-8")
with pytest.raises(SystemExit) as raised:
deploy().translate(bundle, "zh", source)
assert message in str(raised.value), str(raised.value)
assert not (bundle / "manual.zh.json").exists()
def test_the_newest_bundle_built_here_is_what_the_schema_describes() -> None:
"""The real thing, when this machine has built one: what the hand-written
bundle above stands in for."""
built = sorted((p.parent for p in (REPO / "out").glob("bundle_*/*/bundle.json")
if "runtimes" in json.loads(p.read_text("utf-8"))),
key=lambda p: p.stat().st_mtime)
if not built:
pytest.skip("no bundle built here: python scripts/deploy.py --bundle --manifest example_robot")
deploy().validate_app(built[-1])