Repository navigation
[AIT-1081] Update liveobjects uts-to-kotlin skill to generate tests
#1221
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. Weβll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
sacOO7
merged 11 commits into
feature/path-based-liveobjects-implementation
from
feature/liveobjects-uts-tests
Jun 30, 2026
Merged
Changes from 9 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
6ec5d80
Generated UTS doc to better understand the existing UTS infra.
sacOO7 f98d464
docs(uts): add UTS guide (README.md) and standalone website (index.html)
sacOO7 aa0504e
refactor(uts): split test sources into unit/integration tiers + per-tβ¦
sacOO7 a53996c
docs(uts): document direct-sandbox tier and per-module test layout
sacOO7 940b65f
feat(uts-to-kotlin): drive the skill from a module directory via a paβ¦
sacOO7 0aaec39
feat(uts-to-kotlin): deterministic selection via resolver script + evβ¦
sacOO7 0068fe9
feat(uts-to-kotlin): add ably-js β ably-java liveobjects mapping refeβ¦
sacOO7 752b45e
feat(uts): add LiveObjects unit-test helpers (standard_test_pool) + mβ¦
sacOO7 0c59d15
feat(uts): realtime direct-sandbox integration tests + sandbox host rβ¦
sacOO7 6f2c56d
docs/test: apply CodeRabbit + Copilot PR review fixes
sacOO7 d11eb61
feat(uts-skill): add deterministic spec-faithfulness audit to Step 7
sacOO7 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
Large diffs are not rendered by default.
Oops, something went wrong.
628 changes: 628 additions & 0 deletions
628
.claude/skills/uts-to-kotlin/references/objects-mapping.md
Large diffs are not rendered by default.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,179 @@ | ||
| #!/usr/bin/env python3 | ||
| """Resolve a UTS spec module directory to its ably-java test targets. | ||
|
|
||
| Deterministic helper for the uts-to-kotlin skill. Given a UTS spec *module* | ||
| directory (a directory directly under .../specification/uts/), it: | ||
|
|
||
| - validates the path and the module's tier structure, | ||
| - reads uts-package-mapping.json (next to this script's skill dir), | ||
| - resolves, per tier, the target output directory and Kotlin package, and | ||
| - lists the candidate spec files with their derived Kotlin class names. | ||
|
|
||
| Doing this in code (rather than asking the model to eyeball regexes, join | ||
| paths, and hand-convert snake_case -> PascalCase every run) keeps the skill's | ||
| selection phase byte-for-byte deterministic. | ||
|
|
||
| Usage: | ||
| resolve_uts.py <module-dir> # validate + resolve + list specs | ||
| resolve_uts.py <module-dir> --create NAME # add a mapping entry for this | ||
| # module (target base name NAME), | ||
| # then resolve | ||
|
|
||
| Always prints a single JSON object to stdout. On failure: {"ok": false, | ||
| "error": <CODE>, "message": ...} and a non-zero exit. | ||
| """ | ||
| import argparse | ||
| import json | ||
| import re | ||
| import sys | ||
| from pathlib import Path | ||
|
|
||
| SKILL_DIR = Path(__file__).resolve().parent.parent | ||
| MAPPING = SKILL_DIR / "uts-package-mapping.json" | ||
| TIERS = ("unit", "integration", "proxy") | ||
|
|
||
|
|
||
| def fail(code, message): | ||
| print(json.dumps({"ok": False, "error": code, "message": message}, indent=2)) | ||
| sys.exit(1) | ||
|
|
||
|
|
||
| def class_name(md_path: Path) -> str: | ||
| """objects_batch_test.md -> ObjectsBatchTest; instance.md -> InstanceTest.""" | ||
| stem = md_path.stem | ||
| if stem.endswith("_test"): | ||
| stem = stem[: -len("_test")] | ||
| return "".join(part.capitalize() for part in stem.split("_") if part) + "Test" | ||
|
|
||
|
|
||
| def is_nonspec_doc(name: str) -> bool: | ||
| """README/PLAN/*_SUMMARY markdown are docs, not test specs.""" | ||
| if re.fullmatch(r"(README|PLAN)\.md", name, re.IGNORECASE): | ||
| return True | ||
| return name.upper().endswith("_SUMMARY.MD") | ||
|
|
||
|
|
||
| def list_specs(base: Path, exclude_proxy: bool = False): | ||
| """List spec .md files under `base`, deterministically. | ||
|
|
||
| All exclusions are checked against the path **relative to base**, so they | ||
| can't be tripped by an ancestor directory in the checkout path (e.g. a | ||
| clone living under some `.../helpers/...` path). | ||
| """ | ||
| if not base.is_dir(): | ||
| return [] | ||
| specs = [] | ||
| for p in sorted(base.rglob("*.md")): | ||
| rel_parts = p.relative_to(base).parts | ||
| if "helpers" in rel_parts: | ||
| continue | ||
| if exclude_proxy and "proxy" in rel_parts: | ||
| continue | ||
| if is_nonspec_doc(p.name): | ||
| continue | ||
| specs.append(p) | ||
| return specs | ||
|
|
||
|
|
||
| def package_for(target_dir: str) -> str: | ||
| marker = "src/test/kotlin/" | ||
| idx = target_dir.find(marker) | ||
| return target_dir[idx + len(marker):].replace("/", ".") if idx != -1 else "" | ||
|
|
||
|
|
||
| def main(): | ||
| ap = argparse.ArgumentParser() | ||
| ap.add_argument("module_dir") | ||
| ap.add_argument( | ||
| "--create", | ||
| metavar="NAME", | ||
| help="add a mapping for this source module using NAME as the ably-java " | ||
| "module base name, then resolve", | ||
| ) | ||
| args = ap.parse_args() | ||
|
|
||
| raw = args.module_dir.rstrip("/") | ||
| if not re.search(r"/uts/[^/]+$", raw): | ||
| fail("NOT_A_UTS_MODULE_PATH", | ||
| f"{raw!r} is not a module directory directly under uts/ " | ||
| f"(expected .../uts/<module>).") | ||
| module_dir = Path(raw) | ||
| if not module_dir.is_dir(): | ||
| fail("DIR_NOT_FOUND", f"{raw!r} does not exist or is not a directory.") | ||
| if not (module_dir / "unit").is_dir() and not (module_dir / "integration").is_dir(): | ||
| fail("NO_TIER_DIRS", | ||
| f"{raw!r} has no unit/ or integration/ sub-directory; " | ||
| f"not a valid UTS module.") | ||
|
|
||
| source_module = module_dir.name | ||
|
|
||
| if not MAPPING.is_file(): | ||
| fail("MAPPING_NOT_FOUND", f"mapping file not found at {MAPPING}") | ||
| data = json.loads(MAPPING.read_text()) | ||
| packages = data.setdefault("packages", {}) | ||
| test_root = data.get("testRoot", "") | ||
|
|
||
| if args.create: | ||
| target = args.create | ||
| if not re.fullmatch(r"[A-Za-z][A-Za-z0-9_]*", target): | ||
| fail("BAD_TARGET_NAME", | ||
| f"--create target {target!r} must be a simple module base name " | ||
| f"(letters/digits/underscore, e.g. 'liveobjects') so it forms a " | ||
| f"valid path and Kotlin package.") | ||
| new_entry = { | ||
| "unit": f"unit/{target}", | ||
| "integration": f"integration/standard/{target}", | ||
| "proxy": f"integration/proxy/{target}", | ||
| } | ||
| # preserve a hand-maintained "notes" pointer when re-creating an existing entry | ||
| notes = packages.get(source_module, {}).get("notes") | ||
| if notes: | ||
| new_entry["notes"] = notes | ||
| packages[source_module] = new_entry | ||
| MAPPING.write_text(json.dumps(data, indent=2) + "\n") | ||
|
|
||
| mapped = source_module in packages | ||
| entry = packages.get(source_module, {}) | ||
|
|
||
| # Per-module translation notes (ably-js -> ably-java type map etc.), declared by | ||
| # the module's "notes" field in the mapping (a path relative to this skill dir). | ||
| # Read it before translating when present. None when the module declares no notes, | ||
| # or the declared file is missing. | ||
| notes_rel = entry.get("notes") | ||
| notes_path = SKILL_DIR / notes_rel if notes_rel else None | ||
| translation_notes = str(notes_path) if (notes_path and notes_path.is_file()) else None | ||
|
|
||
| src = { | ||
| "unit": module_dir / "unit", | ||
| "integration": module_dir / "integration", | ||
| "proxy": module_dir / "integration" / "proxy", | ||
| } | ||
| specs = { | ||
| "unit": list_specs(src["unit"]), | ||
| "integration": list_specs(src["integration"], exclude_proxy=True), | ||
| "proxy": list_specs(src["proxy"]), | ||
| } | ||
|
|
||
| tiers_out = {} | ||
| for tier in TIERS: | ||
| target_dir = f"{test_root}/{entry[tier]}" if (mapped and tier in entry) else None | ||
| tiers_out[tier] = { | ||
| "present": src[tier].is_dir(), | ||
| "sourceDir": str(src[tier]), | ||
| "targetDir": target_dir, | ||
| "package": package_for(target_dir) if target_dir else None, | ||
| "specs": [{"file": str(p), "className": class_name(p)} for p in specs[tier]], | ||
| } | ||
|
|
||
| print(json.dumps({ | ||
| "ok": True, | ||
| "sourceModule": source_module, | ||
| "mapped": mapped, | ||
| "testRoot": test_root, | ||
| "translationNotes": translation_notes, | ||
| "tiers": tiers_out, | ||
| }, indent=2)) | ||
|
|
||
|
|
||
| if __name__ == "__main__": | ||
| main() | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| { | ||
| "_comment": "Maps each UTS spec module (a dir under specification/uts/) to its target test packages. Output dir = testRoot + '/' + tier entry; Kotlin package = that path after 'src/test/kotlin/' with '/' -> '.'. An optional 'notes' field points (relative to this skill dir) to a per-module ably-js -> ably-java translation reference, read before translating that module. Used by the uts-to-kotlin skill.", | ||
| "testRoot": "uts/src/test/kotlin/io/ably/lib/uts", | ||
| "packages": { | ||
| "realtime": { | ||
| "unit": "unit/realtime", | ||
| "integration": "integration/standard/realtime", | ||
| "proxy": "integration/proxy/realtime" | ||
| }, | ||
| "objects": { | ||
| "unit": "unit/liveobjects", | ||
| "integration": "integration/standard/liveobjects", | ||
| "proxy": "integration/proxy/liveobjects", | ||
| "notes": "references/objects-mapping.md" | ||
| }, | ||
| "rest": { | ||
| "unit": "unit/rest", | ||
| "integration": "integration/standard/rest", | ||
| "proxy": "integration/proxy/rest" | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.