Skip to content

Commit 0068fe9

Browse files
committed
feat(uts-to-kotlin): add ably-js → ably-java liveobjects mapping reference
The objects UTS specs are written in ably-js-style pseudocode, but ably-java is a typed SDK (RTTS1-10 partition). Add references/objects-mapping.md mapping each ably-js symbol to its ably-java equivalent: entry point, async (CompletableFuture/await), the typed PathObject/Instance hierarchies and as* casts, the LiveMapValue write union, creation value types, subscriptions, sync-state events, ValueType, message/operation getters, error codes, path dot-escaping, and the internal-graph caveat for unit specs. Wire it in deterministically: each module declares its translation reference via a `notes` field in uts-package-mapping.json; resolve_uts.py resolves it to `translationNotes` (absolute path, or null), and SKILL.md makes it required reading before Phase 2 when present.
1 parent 0aaec39 commit 0068fe9

4 files changed

Lines changed: 631 additions & 9 deletions

File tree

‎.claude/skills/uts-to-kotlin/SKILL.md‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,15 @@ python3 .claude/skills/uts-to-kotlin/scripts/resolve_uts.py "<module-dir>"
4444

4545
It prints one JSON object. **If `ok` is `false`, relay `message` to the user and stop** — error codes:
4646
`NOT_A_UTS_MODULE_PATH` (not a `.../uts/<module>` directory), `DIR_NOT_FOUND`, `NO_TIER_DIRS` (no `unit/`
47-
or `integration/`). On success it gives `sourceModule`, `mapped`, `testRoot`, and a `tiers` object with one
48-
entry per tier (`unit` / `integration` / `proxy`), each carrying `present`, `sourceDir`, `targetDir`,
49-
`package`, and `specs` (a list of `{file, className}`). Everything downstream reads from this output — treat
50-
it as the single source of truth and don't recompute paths or names by hand.
47+
or `integration/`). On success it gives `sourceModule`, `mapped`, `testRoot`, `translationNotes`, and a
48+
`tiers` object with one entry per tier (`unit` / `integration` / `proxy`), each carrying `present`,
49+
`sourceDir`, `targetDir`, `package`, and `specs` (a list of `{file, className}`). Everything downstream
50+
reads from this output — treat it as the single source of truth and don't recompute paths or names by hand.
51+
52+
`translationNotes` is the path to a per-module ably-js → ably-java type/interface map when the module
53+
declares one (its `notes` field in `uts-package-mapping.json`, e.g. `objects` →
54+
`references/objects-mapping.md`), else `null`. When it's non-null, it is **required reading before
55+
Phase 2** — see Step 1.
5156

5257
## Step B — Confirm or create the target mapping
5358

@@ -113,9 +118,15 @@ When translating several specs, do Steps 1–4 (generate the file) for every spe
113118
compiling once is faster than per-file and surfaces cross-file issues together. For a single spec, just go
114119
through the steps in order.
115120

116-
## Step 1 — Read the spec
121+
## Step 1 — Read the spec (and any module translation notes)
122+
123+
**If Step A reported a non-null `translationNotes`, read that file first (once per run).** UTS specs are
124+
written in a language-agnostic pseudocode that mirrors the *ably-js* API; for modules whose ably-java types
125+
diverge (e.g. `objects` → `liveobjects`, where ably-java is a typed SDK with a partitioned `PathObject` /
126+
`Instance` hierarchy and a `LiveMapValue` write union), the notes map each spec symbol to its ably-java
127+
equivalent. Skipping them yields tests that read like ably-js and won't compile.
117128

118-
Read the current spec file (the one being translated from the Step D selection). Identify:
129+
Then read the current spec file (the one being translated from the Step D selection). Identify:
119130
- All test cases — each has a structured ID like `realtime/unit/RSA4c2/callback-error-connecting-disconnected-0` and a description
120131
- The protocol used (WebSocket for Realtime, HTTP for REST)
121132
- Any timer usage (`enable_fake_timers`, `ADVANCE_TIME`)

0 commit comments

Comments
 (0)