Skip to content

Commit 940b65f

Browse files
committed
feat(uts-to-kotlin): drive the skill from a module directory via a package mapping
Rework the uts-to-kotlin skill to translate a whole UTS module at once instead of a single spec file: - Take a UTS module directory (e.g. .../specification/uts/objects) and validate it sits directly under uts/ with a standard tier structure. - Resolve the target ably-java package via uts-package-mapping.json (a new config file alongside the skill): a shared `testRoot` parent plus a `packages` table mapping each source module to its per-tier output dir (so objects -> liveobjects is explicit). Offer to create a mapping when one is missing. - Let the user pick a tier (unit / integration / proxy) and then translate all specs or a selected subset, looping each through the existing per-spec translation steps. Phase 1 (selection: Steps A-D) is new; Phase 2 (per-spec translation: Steps 1-7) keeps the existing rules, with Step 1/2 adjusted to consume the looped spec and the pre-resolved target.
1 parent a53996c commit 940b65f

2 files changed

Lines changed: 145 additions & 42 deletions

File tree

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

Lines changed: 124 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,145 @@
11
---
2-
description: "Translate a UTS pseudocode test spec into Kotlin tests in the uts module. Usage: /uts-to-kotlin <path-to-spec-file>"
2+
description: "Translate the UTS pseudocode test specs in a whole module directory into runnable Kotlin tests in the ably-java uts module. Takes a UTS module directory (e.g. .../specification/uts/objects), validates its structure, resolves the target ably-java module, lets you pick a tier (unit/integration/proxy) and which specs, then derives a Kotlin test per spec. Usage: /uts-to-kotlin <path-to-uts-module-directory>"
33
allowed-tools: Bash, Read, Edit, Write
44
---
55

6-
Translate the UTS pseudocode test spec at `$ARGUMENTS` into a runnable Kotlin test in the `uts` module.
6+
Translate the UTS pseudocode test specs under the **module directory** `$ARGUMENTS` into runnable Kotlin
7+
tests in the ably-java `uts` module.
8+
9+
`$ARGUMENTS` is a UTS *module* directory — a directory sitting directly under `.../specification/uts/`,
10+
e.g. `/Users/sachinsh/ably-specification/specification/uts/objects`. Its name (`objects`, `realtime`,
11+
`rest`, …) is the **source module**. A module directory holds many spec files, organised into tiers
12+
(`unit/`, `integration/`, and `integration/proxy/`).
13+
14+
The work happens in two phases:
15+
16+
- **Phase 1 — Selection (Steps A–D below):** validate the directory, resolve the *target* ably-java
17+
module via `uts-package-mapping.json`, pick a tier, and pick which spec files to translate.
18+
- **Phase 2 — Per-spec translation (Steps 1–7):** for each selected spec file, derive a Kotlin test.
719

820
Reference: [Writing Derived Tests](https://raw.githubusercontent.com/ably/specification/refs/heads/main/uts/docs/writing-derived-tests.md)
921

1022
---
1123

12-
## Step 0 — Validate arguments
24+
# Phase 1 — Selection
25+
26+
## Step A — Validate the module directory
1327

14-
**If `$ARGUMENTS` is empty or blank**, stop immediately and tell the user:
28+
`$ARGUMENTS` must be a UTS **module directory** sitting directly under a `uts/` parent.
29+
30+
**If `$ARGUMENTS` is empty or blank**, stop and tell the user:
1531

1632
```
17-
Usage: /uts-to-kotlin <path-to-spec-file>
33+
Usage: /uts-to-kotlin <path-to-uts-module-directory>
1834
1935
Example:
20-
/uts-to-kotlin lib/src/spec/uts/test/realtime/unit/connection/connection_state_machine_test.md
36+
/uts-to-kotlin /Users/sachinsh/ably-specification/specification/uts/objects
2137
22-
Please re-run the command with the path to a UTS pseudocode spec file.
38+
Pass a UTS module directory (a directory directly under .../specification/uts/), not a single spec file.
2339
```
2440

25-
Do not proceed to Step 1.
26-
27-
**If `$ARGUMENTS` is provided but does not end in `.md`**, stop and tell the user:
41+
Otherwise validate with these checks. Substitute the real path for `DIR=` (shell variables do **not**
42+
persist between separate `Bash` calls, and `$ARGUMENTS` is a text placeholder, not a shell variable — so
43+
set `DIR` literally each time you need it):
2844

45+
```bash
46+
DIR="/absolute/path/to/the/module" # the path passed in, trailing slash removed
47+
# 1. Must be a directory directly under a `uts/` parent: .../uts/<module>
48+
[[ "$DIR" =~ /uts/[^/]+$ ]] || echo "NOT_A_UTS_MODULE_PATH"
49+
# 2. Must exist as a directory
50+
test -d "$DIR" || echo "DIR_NOT_FOUND"
51+
# 3. Standard structure: at least one recognised tier directory
52+
{ test -d "$DIR/unit" || test -d "$DIR/integration"; } || echo "NO_TIER_DIRS"
53+
echo "MODULE=$(basename "$DIR")"
2954
```
30-
Error: "<value>" does not look like a spec file path (expected a .md file).
3155

32-
Usage: /uts-to-kotlin <path-to-spec-file>
33-
```
56+
- If `NOT_A_UTS_MODULE_PATH` → the path isn't `.../uts/<module-name>`. Tell the user the path must point at a
57+
module directory directly under `uts/` (e.g. `.../specification/uts/objects`) and stop.
58+
- If `DIR_NOT_FOUND` → tell the user the directory doesn't exist and stop.
59+
- If `NO_TIER_DIRS` → the directory has no `unit/` or `integration/` sub-directory, so it isn't a valid UTS
60+
module. Tell the user and stop.
3461

35-
Do not proceed to Step 1.
62+
The **source module** is the directory's base name (`MODULE=` above) — `objects`, `realtime`, `rest`, …
3663

37-
**If `$ARGUMENTS` ends in `.md` but the file does not exist** (check with `test -f "$ARGUMENTS"`), stop and tell the user:
64+
Only continue once all three checks pass.
3865

39-
```
40-
Error: file not found: "<value>"
66+
## Step B — Resolve the target ably-java module
67+
68+
Spec modules don't always share a name with their ably-java counterpart (e.g. `objects` → `liveobjects`),
69+
so the mapping is explicit. Read `uts-package-mapping.json`, which sits alongside this skill at
70+
`.claude/skills/uts-to-kotlin/uts-package-mapping.json`. The file has a single shared parent — `testRoot`
71+
(the directory, from the ably-java repo root, that every target lives under) — and a `packages` table whose
72+
keys are source module names. Each tier value is the output directory **relative to `testRoot`**:
4173

42-
Check the path and try again.
74+
```json
75+
"testRoot": "uts/src/test/kotlin/io/ably/lib/uts",
76+
"packages": {
77+
"objects": {
78+
"unit": "unit/liveobjects",
79+
"integration": "integration/standard/liveobjects",
80+
"proxy": "integration/proxy/liveobjects"
81+
}
82+
}
4383
```
4484

45-
Do not proceed to Step 1.
85+
Resolve a tier to its concrete target like so:
86+
- **Output directory** = `testRoot` + `/` + the tier entry (e.g. `uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects`).
87+
- **Kotlin package** = that path's segment **after `src/test/kotlin/`** with `/` replaced by `.` (e.g. `io.ably.lib.uts.unit.liveobjects`).
88+
89+
Then:
90+
- **If the source module has an entry**, show its three resolved target dirs and ask the user to confirm it,
91+
or to pick a different existing module instead.
92+
- **If it has no entry**, tell the user there's no mapping yet and offer to create one. Ask for the target
93+
module base name (default to the source name; suggest a rename only when the SDK uses different
94+
terminology, e.g. `objects` → `liveobjects`). Then add a new entry to `uts-package-mapping.json` with the
95+
three `testRoot`-relative paths — `unit/<target>`, `integration/standard/<target>`, and
96+
`integration/proxy/<target>` — and save the file before continuing.
97+
98+
## Step C — Choose the tier
4699

47-
Only continue to Step 1 once the file is confirmed to exist.
100+
Offer the tiers that actually exist in the source module, and map each to its source spec directory and the
101+
target output directory from Step B:
102+
103+
| Tier | Source spec directory | Target (mapping entry, joined onto `testRoot`) | Per-spec translation flow |
104+
|---|---|---|---|
105+
| **unit** | `<module>/unit/` | mapping `unit` (e.g. `unit/liveobjects`) | mocked transport — Steps 1–7 below |
106+
| **integration** (direct sandbox) | `<module>/integration/` *(excluding `proxy/` and `helpers/`)* | mapping `integration` (e.g. `integration/standard/liveobjects`) | real sandbox, no faults — see **Proxy integration tests** but drop the `ProxySession`/`connectThroughProxy` wiring |
107+
| **proxy** | `<module>/integration/proxy/` | mapping `proxy` (e.g. `integration/proxy/liveobjects`) | real sandbox + fault injection — see **Proxy integration tests** |
108+
109+
The tier you pick here fixes the target directory/package and which translation flow Phase 2 uses — you do
110+
**not** re-detect it per spec.
111+
112+
## Step D — Choose which specs to translate
113+
114+
List the candidate spec files in the chosen tier's source directory (recurse, but **exclude** any
115+
`helpers/` directory and non-spec docs like `PLAN.md`, `README.md`, or `*_SUMMARY.md`). Substitute the
116+
real module path for `DIR` again:
117+
118+
```bash
119+
DIR="/absolute/path/to/the/module"
120+
# unit
121+
find "$DIR/unit" -name '*.md' -not -path '*/helpers/*' | sort
122+
# integration (direct sandbox) — exclude the proxy subtree
123+
find "$DIR/integration" -name '*.md' -not -path '*/proxy/*' -not -path '*/helpers/*' | sort
124+
# proxy
125+
find "$DIR/integration/proxy" -name '*.md' -not -path '*/helpers/*' | sort
126+
```
127+
128+
Present the list and ask the user whether to **translate all** of them or **select specific** files. Then,
129+
for each selected spec, run Phase 2 (Steps 1–7).
48130

49131
---
50132

133+
# Phase 2 — Per-spec translation
134+
135+
Run this for **each** spec file selected in Step D. When translating several specs, do Steps 1–4 (generate
136+
the file) for every spec first, then run Step 5 (compile) once for the whole module, then Steps 6–7 per
137+
file — compiling once is faster than per-file and surfaces cross-file issues together. For a single spec,
138+
just go through Steps 1–7 in order.
139+
51140
## Step 1 — Read the spec
52141

53-
Read the file at `$ARGUMENTS`. Identify:
142+
Read the current spec file (the one being translated from the Step D selection). Identify:
54143
- All test cases — each has a structured ID like `realtime/unit/RSA4c2/callback-error-connecting-disconnected-0` and a description
55144
- The protocol used (WebSocket for Realtime, HTTP for REST)
56145
- Any timer usage (`enable_fake_timers`, `ADVANCE_TIME`)
@@ -59,30 +148,23 @@ Read the file at `$ARGUMENTS`. Identify:
59148

60149
## Step 2 — Determine output path and package
61150

62-
Map the spec path to a test path. **Tests are organised tier-first** (`unit/` vs `integration/standard/`
63-
vs `integration/proxy/`), then **by module** (`realtime`, `rest`, `liveobjects`, …), all under the
64-
`io.ably.lib.uts` package. (`…/uts/` below is shorthand for `uts/src/test/kotlin/io/ably/lib/uts/`.)
65-
66-
| Spec location | Test location | Package |
67-
|---|---|---|
68-
| `.../<module>/unit/<…>/<name>.md` | `…/uts/unit/<module>/<Name>Test.kt` | `io.ably.lib.uts.unit.<module>` |
69-
| `.../<module>/integration/<…>/<name>.md` (direct sandbox) | `…/uts/integration/standard/<module>/<Name>Test.kt` | `io.ably.lib.uts.integration.standard.<module>` |
70-
| `.../<module>/integration/<…>/<name>.md` (proxy) | `…/uts/integration/proxy/<module>/<Name>Test.kt` | `io.ably.lib.uts.integration.proxy.<module>` |
71-
72-
`<module>` is the SDK area — `realtime`, `rest`, `liveobjects`, … (existing folders: `unit/realtime/`,
73-
`unit/liveobjects/`). The spec's own `<sub>` grouping (e.g. `connection/`) is **not** carried into a
74-
sub-package — tests sit directly under the tier/module folder (e.g. `connection_recovery_test.md` →
75-
`…/uts/unit/realtime/ConnectionRecoveryTest.kt`).
76-
77-
Class name: take the file name, strip `_test` suffix, convert `snake_case` → `PascalCase`, append `Test`.
151+
The target directory and package are already fixed by the tier chosen in Step C and the mapping resolved in
152+
Step B — you do not re-derive them from the spec path. `<targetDir>` is `testRoot` + the tier entry (e.g.
153+
`uts/src/test/kotlin/io/ably/lib/uts/unit/liveobjects`) and `<package>` is its dotted form after
154+
`src/test/kotlin/` (e.g. `io.ably.lib.uts.unit.liveobjects`).
78155

79-
**Integration specs come in two kinds:**
80-
- Those that **inject faults** (reference `create_proxy_session()`, proxy `rules`, `trigger_action`, `get_log`, or `uts/test/realtime/integration/helpers/proxy.md`) are **proxy** tests under `integration/proxy/<module>/` — follow the **Proxy integration tests** section at the end of this skill instead of the unit-test rules below.
81-
- Those that exercise only **happy-path interop** against the real sandbox (no fault injection) are **direct sandbox** tests under `integration/standard/<module>/`. They use `SandboxApp` alone (no `ProxySession`), connecting straight to `ProxyManager.sandboxRealtimeHost` / `sandboxRestHost`. *(No example exists yet — model the suite setup/teardown on the proxy section but drop the `ProxySession`/`connectThroughProxy` wiring.)*
156+
Only the **class name** comes from the spec file: take its file name, strip a `_test` suffix if present,
157+
convert `snake_case` → `PascalCase`, and append `Test`. Examples: `objects_batch_test.md` →
158+
`ObjectsBatchTest`; `live_counter_api.md` → `LiveCounterApiTest`; `connection_recovery_test.md` →
159+
`ConnectionRecoveryTest`.
82160

83-
Example: `connection_state_machine_test.md` → `ConnectionStateMachineTest`
161+
The spec's own `<sub>` grouping (e.g. `connection/`, `channels/`) is **not** carried into a sub-package —
162+
every test sits directly in `<targetDir>`. Output file: `<targetDir>/<ClassName>.kt`, with
163+
`package <package>` at the top.
84164

85-
Package: derived from the output path under `kotlin/`.
165+
The chosen tier also fixes the translation flow: **unit** → the rules in Steps 3–4 below; **integration**
166+
(direct sandbox) and **proxy** → the **Proxy integration tests** section (direct sandbox drops the
167+
`ProxySession`/`connectThroughProxy` wiring; see Step C).
86168

87169
---
88170

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"_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 '/' -> '.'. Used by the uts-to-kotlin skill.",
3+
"testRoot": "uts/src/test/kotlin/io/ably/lib/uts",
4+
"packages": {
5+
"realtime": {
6+
"unit": "unit/realtime",
7+
"integration": "integration/standard/realtime",
8+
"proxy": "integration/proxy/realtime"
9+
},
10+
"objects": {
11+
"unit": "unit/liveobjects",
12+
"integration": "integration/standard/liveobjects",
13+
"proxy": "integration/proxy/liveobjects"
14+
},
15+
"rest": {
16+
"unit": "unit/rest",
17+
"integration": "integration/standard/rest",
18+
"proxy": "integration/proxy/rest"
19+
}
20+
}
21+
}

0 commit comments

Comments
 (0)