doricomcp 0.1.0__py3-none-any.whl

doricomcp/analysis.py

@@ -0,0 +1,161 @@
+"""Voice-leading check over read_music data: parallel and hidden fifths/octaves, crossings, spacing, leaps and,
+with a chord plan, doublings and missing chord tones. Pure Python on what read_music returns; no Dorico access.
+
+Depends on: model.
+"""
+import re
+from fractions import Fraction
+from itertools import pairwise
+
+from .model import frac, spelling_to_midi
+
+PC = {"C": 0, "D": 2, "E": 4, "F": 5, "G": 7, "A": 9, "B": 11}
+# chord quality -> semitones above the root of (third, fifth, seventh); None = not in the chord
+QUALITIES = {"": (4, 7, None), "m": (3, 7, None), "dim": (3, 6, None), "aug": (4, 8, None), "sus4": (5, 7, None),
+             "sus2": (2, 7, None), "7": (4, 7, 10), "maj7": (4, 7, 11), "m7": (3, 7, 10), "m7b5": (3, 6, 10),
+             "dim7": (3, 6, 9), "mmaj7": (3, 7, 11)}
+CHORD_RX = re.compile(r"^([A-G])(#|b)?(maj7|mmaj7|m7b5|dim7|dim|aug|sus4|sus2|m7|m|7|ø7|o7|ø|o|)(?:/([A-G](?:#|b)?))?$")
+ALIASES = {"ø7": "m7b5", "ø": "m7b5", "o7": "dim7", "o": "dim"}
+NAMES = {0: "unison/octave", 7: "fifth"}
+
+
+def _pc(name: str) -> int:
+    return (PC[name[0]] + {"#": 1, "b": -1}.get(name[1:2], 0)) % 12
+
+
+def parse_chord(sym: str) -> dict:
+    m = CHORD_RX.match(sym.strip())
+    if not m:
+        raise ValueError(f"chord {sym!r}: like D, Bm, A7, F#dim, Gmaj7, Bm7b5, D/F#")
+    root = _pc(m.group(1) + (m.group(2) or ""))
+    third, fifth, seventh = QUALITIES[ALIASES.get(m.group(3), m.group(3))]
+    roles = {root: "root", (root + third) % 12: "third", (root + fifth) % 12: "fifth"}
+    if seventh is not None:
+        roles[(root + seventh) % 12] = "seventh"
+    return {"symbol": sym.strip(), "roles": roles, "bass": _pc(m.group(4)) if m.group(4) else None,
+            "major": third == 4}
+
+
+def parse_plan(plan: str) -> list[tuple[int, Fraction, dict]]:
+    """"28 D, 28:2 A7, 29 Bm/F#" -> [(bar, beat, chord)], sorted."""
+    out = []
+    for item in filter(None, (x.strip() for x in re.split(r"[,;\n]", plan))):
+        where, _, sym = item.partition(" ")
+        bar, _, beat = where.partition(":")
+        out.append((int(bar), frac(beat or 0), parse_chord(sym)))
+    return sorted(out, key=lambda x: (x[0], x[1]))
+
+
+def _lines(read: dict) -> dict[int, list[tuple]]:
+    """voice -> [(start, end, midi, pitch, bar, beat)]; a chord in one voice counts by its top note."""
+    out = {}
+    for v in read["voices"]:
+        notes = []
+        for i in v["items"]:
+            if i["type"] not in ("note", "chord"):
+                continue
+            k = max(range(len(i["midi"])), key=lambda j: i["midi"][j] or spelling_to_midi(i["pitches"][j]) or 0)
+            dur = max(frac(d) for d in (i["dur"] if isinstance(i["dur"], list) else [i["dur"]]))
+            notes.append((frac(i["pos"]), frac(i["pos"]) + dur, i["midi"][k] or spelling_to_midi(i["pitches"][k]),
+                          i["pitches"][k], i["bar"], i["beat"]))
+        out[v["voice"]] = notes
+    return out
+
+
+def check(read: dict, order: list[int] | None = None, plan: str | None = None, key: str | None = None,
+          max_leap: int = 12, limit: int = 300) -> dict:
+    """order: voices from highest to lowest (default: by average pitch). key: tonic for leading-tone doubling
+    ("D", "Bm"; minor keys use the raised seventh). plan: chords in force, "bar[:beat] symbol, ..."."""
+    lines = _lines(read)
+    lines = {v: ns for v, ns in lines.items() if ns}
+    order = [v for v in (order or sorted(lines, key=lambda v: -sum(n[2] for n in lines[v]) / len(lines[v]))) if v in lines]
+    chords = parse_plan(plan) if plan else []
+    leading = (_pc(key.rstrip("m")) - 1) % 12 if key else None
+    problems = []
+
+    def add(kind, at, voices, detail):
+        problems.append({"bar": at[0], "beat": at[1], "kind": kind, "voices": voices, "detail": detail})
+
+    for v in order:  # melodic leaps
+        for a, b in pairwise(lines[v]):
+            d = abs(b[2] - a[2])
+            if d > max_leap or d == 6:
+                add("leap" if d != 6 else "tritone leap", (b[4], b[5]), [v], f"{a[3]} -> {b[3]} ({d} semitones)")
+
+    times = sorted({n[0] for ns in lines.values() for n in ns})
+    prev = None
+    for t in times:
+        cur = {v: next((n for n in lines[v] if n[0] <= t < n[1]), None) for v in order}
+        at = next((n[4], n[5]) for n in cur.values() if n and n[0] == t)
+        here = [v for v in order if cur[v]]
+        for hi, lo in pairwise(here):
+            if cur[hi][2] < cur[lo][2]:
+                add("crossing", at, [hi, lo], f"{cur[hi][3]} below {cur[lo][3]}")
+        for hi, lo in pairwise(here[:-1]):  # upper voices; the bass may be further away
+            if cur[hi][2] - cur[lo][2] > 12:
+                add("spacing", at, [hi, lo], f"{cur[hi][3]} - {cur[lo][3]} wider than an octave")
+        if prev:
+            for i, a in enumerate(order):
+                for b in order[i + 1:]:
+                    pa, pb, ca, cb = prev.get(a), prev.get(b), cur[a], cur[b]
+                    if not (pa and pb and ca and cb) or (pa is ca and pb is cb):
+                        continue
+                    da, db = ca[2] - pa[2], cb[2] - pb[2]
+                    if not (da and db):
+                        continue
+                    i1, i2 = (pa[2] - pb[2]) % 12, (ca[2] - cb[2]) % 12
+                    if i1 == i2 and i1 in NAMES:
+                        name = "unisons" if pa[2] == pb[2] and ca[2] == cb[2] else NAMES[i1] + "s"
+                        motion = "parallel" if da * db > 0 else "contrary"
+                        add(f"{motion} {name}", at, [a, b], f"{pa[3]}/{pb[3]} -> {ca[3]}/{cb[3]}")
+                    elif (a, b) == (order[0], order[-1]) and da * db > 0 and i2 in NAMES and abs(da) > 2:
+                        add(f"hidden {NAMES[i2]}", at, [a, b], f"{pa[3]}/{pb[3]} -> {ca[3]}/{cb[3]}, upper voice leaps")
+        if chords and len(here) >= 3:
+            ch = next((c for bar, beat, c in reversed(chords) if (bar, beat) <= (at[0], frac(at[1]))), None)
+            if ch:
+                pcs = [cur[v][2] % 12 for v in here]
+                count = {p: pcs.count(p) for p in set(pcs)}
+                roles = {ch["roles"].get(p): n for p, n in count.items()}
+                if roles.get("third", 0) > 1 and ch["major"]:
+                    add("doubled third", at, here, f"{ch['symbol']}: major third doubled")
+                if roles.get("seventh", 0) > 1:
+                    add("doubled seventh", at, here, ch["symbol"])
+                if leading is not None and count.get(leading, 0) > 1:
+                    add("doubled leading tone", at, here, ch["symbol"])
+                if "third" not in roles:
+                    add("missing third", at, here, ch["symbol"])
+                if foreign := sorted({cur[v][3] for v in here if cur[v][2] % 12 not in ch["roles"]}):
+                    add("non-chord tone", at, here, f"{ch['symbol']}: {' '.join(foreign)}")
+                if ch["bass"] is not None and cur[here[-1]][2] % 12 != ch["bass"]:
+                    add("bass", at, [here[-1]], f"{ch['symbol']}: bass is {cur[here[-1]][3]}")
+        prev = cur
+    summary = {}
+    for p in problems:
+        summary[p["kind"]] = summary.get(p["kind"], 0) + 1
+    problems.sort(key=lambda p: (p["bar"], frac(p["beat"])))
+    return {"voices_high_to_low": order, "verticals": len(times), "summary": summary, "problems": problems[:limit],
+            **({"truncated": len(problems) - limit} if len(problems) > limit else {})}
+
+
+if __name__ == "__main__":
+    def voice(vid, notes):
+        items, t = [], Fraction(0)
+        for p, d in notes:
+            items.append({"type": "note", "pos": str(t), "dur": d, "bar": 1 + int(t // 3), "beat": str(t % 3),
+                          "pitches": [p], "midi": [spelling_to_midi(p)]})
+            t += frac(d)
+        return {"voice": vid, "items": items}
+
+    # outer voices in parallel fifths D5/G4 -> E5/A4; the middle voice drops below the bass, then leaps a ninth
+    rd = {"voices": [voice(1, [("D5", "1"), ("E5", "1"), ("F#5", "1")]), voice(2, [("B4", "1"), ("C#4", "1"), ("D5", "1")]),
+                     voice(3, [("G4", "1"), ("A4", "1"), ("A4", "1")])]}
+    r = check(rd, order=[1, 2, 3])
+    kinds = r["summary"]
+    assert kinds == {"parallel fifths": 1, "crossing": 1, "spacing": 1, "leap": 1}, r
+    # a chord plan: D major with a doubled F#, then A7 with no third
+    rd = {"voices": [voice(1, [("F#5", "1"), ("G5", "1")]), voice(2, [("F#4", "1"), ("E4", "1")]),
+                     voice(3, [("D3", "1"), ("A2", "1")])]}
+    r = check(rd, order=[1, 2, 3], plan="1 D, 1:1 A7", key="D")
+    assert r["summary"].get("doubled third") == 1 and r["summary"].get("missing third") == 1, r
+    assert parse_chord("Bm7b5")["roles"] == {11: "root", 2: "third", 5: "fifth", 9: "seventh"}
+    print("analysis self-check ok")

doricomcp/bridge.py

@@ -0,0 +1,153 @@
+"""Lua transaction bridge: one call = one generated self-contained Lua script run by Script.RunScript.
+
+The script is lua/lib.lua + `local REQ = <request literal>` + a dispatcher. It writes `<id>.json`
+then `<id>.done` (the marker is written last, so a present marker means the JSON is complete).
+Script.RunScript returns before the Lua runs, so Python waits on the marker.
+A script is one undo step in Dorico; a read-only script adds none.
+
+Depends on: logtail, rc, windows.
+"""
+import asyncio
+import json
+import pathlib
+import subprocess
+import time
+import uuid
+
+from .logtail import LOG
+from .rc import HOME, RemoteControl
+
+RUN_DIR = HOME / "run"  # no spaces: the path goes into a command string unescaped
+LIB = pathlib.Path(__file__).with_name("lua") / "lib.lua"
+
+
+class LuaError(RuntimeError):
+    pass
+
+
+class StillRunning(LuaError):
+    """The script has not finished: Dorico is blocked (dialog) or very slow. It may still change the score, so
+    nothing may be read back or undone against it."""
+
+
+HARD_LIMIT = 600.0  # one fixed ceiling for a genuinely hung Dorico; dialogs are caught much earlier
+
+
+def lua_literal(v) -> str:
+    """Python value -> Lua literal (dicts become tables keyed by string, lists 1-based arrays)."""
+    if v is None:
+        return "nil"
+    if v is True or v is False:
+        return "true" if v else "false"
+    if isinstance(v, int):
+        return str(v)
+    if isinstance(v, float):
+        return repr(v)
+    if isinstance(v, str):
+        return '"' + "".join(c if 32 <= ord(c) < 127 and c not in '"\\' else "".join(f"\\{b:03d}" for b in c.encode()) for c in v) + '"'
+    if isinstance(v, (list, tuple)):
+        return "{" + ",".join(lua_literal(x) for x in v) + "}"
+    if isinstance(v, dict):
+        return "{" + ",".join(f"[{lua_literal(str(k))}]={lua_literal(x)}" for k, x in v.items()) + "}"
+    raise TypeError(f"cannot pass {type(v).__name__} to Lua")
+
+
+async def _wait_finished(script: str, offset: int, deadline: float):
+    needle = f"notifyPostCommandExecute: Script.RunScript?ScriptPath={script}".encode()
+    def seen() -> bool:
+        try:
+            with open(LOG, "rb") as f:
+                f.seek(offset)
+                return needle in f.read()
+        except FileNotFoundError:
+            return True
+    while time.monotonic() < deadline:
+        if await asyncio.to_thread(seen):
+            return
+        await asyncio.sleep(0.01)
+    raise LuaError(f"{script}: Dorico did not finish the script command in time")
+
+
+def _dialogs() -> list[dict]:
+    from .windows import dialogs
+    try:
+        return dialogs()
+    except (OSError, RuntimeError, subprocess.SubprocessError, ValueError):  # no swiftc / no permission: best effort
+        return []
+
+
+class Bridge:
+    def __init__(self, rc: RemoteControl):
+        self.rc = rc
+        self._lock = asyncio.Lock()
+
+    async def run(self, op: str, timeout: float = 20.0, extra_lua: str = "", **req):
+        """Run lib op `op` with request fields `req`; return its result or raise LuaError."""
+        RUN_DIR.mkdir(parents=True, exist_ok=True)
+        rid = uuid.uuid4().hex
+        script, out, done = (RUN_DIR / f"{rid}{ext}" for ext in (".lua", ".json", ".done"))
+        req["op"] = op
+        script.write_text(
+            f"local REQ = {lua_literal(req)}\n"
+            f"local OUT, DONE = {lua_literal(str(out))}, {lua_literal(str(done))}\n"
+            + LIB.read_text() + "\n" + extra_lua + "\nreturn RUN()\n")
+        async with self._lock:
+            running = False
+            try:
+                log0 = LOG.stat().st_size if LOG.exists() else 0
+                await self.rc.command(f"Script.RunScript?ScriptPath={script}")
+                running = True
+                t0 = time.monotonic()
+                # Never give up on a running script: Dorico interleaves Remote Control commands with the script's
+                # own doCommand calls, so a read or Edit.Undo sent now would land in the middle of it (an undo
+                # once landed between two NoteInput.Pitch commands, and the script kept typing).
+                check = t0 + timeout
+                while not done.exists():
+                    now = time.monotonic()
+                    if now > check:
+                        if d := _dialogs():
+                            raise StillRunning(f"op {op!r}: Dorico shows a dialog ({d[0]['w']}x{d[0]['h']} '{d[0]['name']}') "
+                                               "and the edit has not finished; answer it with list_dialogs + dialog_click (or in Dorico)")
+                        if now - t0 > HARD_LIMIT:
+                            raise StillRunning(f"op {op!r}: Dorico has not finished after {now - t0:.0f}s")
+                        check = now + 5
+                    await asyncio.sleep(0.02)
+                running = False
+                payload = json.loads(out.read_text())
+                # The marker is written inside the script; Dorico is still executing RunScript until it logs
+                # notifyPostCommandExecute. Commands sent before that (e.g. Edit.Undo) get kCommandNotAllowed.
+                await _wait_finished(str(script), log0, time.monotonic() + timeout)
+            finally:
+                # a script still running writes its markers later; leave them rather than race it
+                for p in () if running else (script, out, done):
+                    p.unlink(missing_ok=True)
+        if not payload.get("ok"):
+            raise LuaError(f"op {op!r} failed in Dorico: {payload.get('error')}")
+        return payload.get("result")
+
+
+if __name__ == "__main__":
+    import tempfile
+
+    class SlowDorico:  # writes the result 0.5 s after RunScript, well past the 0.1 s timeout
+        def __init__(self):
+            self.sent = []
+
+        async def command(self, c):
+            self.sent.append(c)
+            script = pathlib.Path(c.split("ScriptPath=", 1)[1])
+            out, done = (script.with_suffix(x) for x in (".json", ".done"))
+            asyncio.get_running_loop().call_later(0.5, lambda: (out.write_text('{"ok": true, "result": 42}'), done.write_text("1")))
+
+    async def main():
+        global RUN_DIR, _wait_finished
+        RUN_DIR = pathlib.Path(tempfile.mkdtemp())
+
+        async def finished(*a):
+            return None
+        _wait_finished = finished
+        rc = SlowDorico()
+        assert await Bridge(rc).run("tx", timeout=0.1) == 42
+        assert len(rc.sent) == 1 and not list(RUN_DIR.iterdir()), (rc.sent, list(RUN_DIR.iterdir()))
+    asyncio.run(main())
+    print("bridge self-check ok: a slow script is waited for, nothing else is sent meanwhile")

doricomcp/catalog.py

@@ -0,0 +1,154 @@
+"""Dorico's command list, enum values, property schemas and library entries (doricomcp/data/), the live
+confirmation matrix, and command validation.
+
+Depends on: nothing else in the package.
+"""
+import json
+import pathlib
+import re
+from functools import cache
+from urllib.parse import parse_qsl
+
+DATA = pathlib.Path(__file__).resolve().parent / "data"
+CONFIRMED = DATA / "confirmed.json"
+
+
+def _load(p):
+    return json.loads(pathlib.Path(p).read_text())
+
+
+@cache
+def commands() -> dict[str, dict]:
+    d = _load(DATA / "commands.json")
+    out = {c["name"]: c for c in d["commands"]}
+    for n in d.get("observed_but_not_listed", []):
+        out.setdefault(n, {"name": n, "group": n.split(".")[0], "parameters": {}, "internal": True})
+    for n in _load(DATA / "commands_not_in_getcommands.json"):
+        out.setdefault(n, {"name": n, "group": n.split(".")[0], "parameters": {}, "internal": True})
+    return out
+
+
+@cache
+def enums() -> dict[str, list]:
+    return _load(DATA / "enums.json")
+
+
+@cache
+def property_names() -> dict[str, list]:
+    return _load(DATA / "property_names.json")["by_family"]
+
+
+@cache
+def property_schemas() -> dict:
+    return _load(DATA / "rc_property_schemas.json")
+
+
+def property_info(name: str) -> dict | None:
+    """Schema (valueType, enumValues, displayName) for a property name from the live RC dumps, if known."""
+    for et, d in property_schemas().items():
+        for p in d["propertieslist"]["properties"]:
+            if p["name"] == name:
+                return {**p, "seen_on": et}
+    fam = next((f for f, names in property_names().items() if name in names), None)
+    return {"name": name, "family": fam} if fam else None
+
+
+@cache
+def library_dump(collection: str) -> list[dict]:
+    p = DATA / "library" / f"library_{collection}.json"
+    return _load(p)[0]["libraryentities"] if p.exists() else []
+
+
+def _norm(s: str) -> str:
+    return re.sub(r"[^a-z0-9]", "", s.lower())
+
+
+def technique(value: str, lib: list[dict] | None = None) -> dict:
+    """A playing technique by library id ("pta.pizzText"), name or abbreviation ("pizz.", "arco", "con sord.",
+    "sul pont.", "ord."): {entityID, name}. lib: the score's live library (with the user's own techniques); default
+    the catalogued one. Raises ValueError listing candidates when unknown or ambiguous."""
+    lib = lib or library_dump("kPlayingTechniqueAppearanceCollection")
+    if any(e["entityID"] == value for e in lib):
+        return next(e for e in lib if e["entityID"] == value)
+    want = _norm(value)
+
+    def keys(e):
+        abbr = re.findall(r"\(([^)]*)\)", e["name"])
+        return {_norm(e["name"]), _norm(e["entityID"].removeprefix("pta.").removesuffix("Text")), *map(_norm, abbr)}
+
+    hits = [e for e in lib if want in keys(e)] or [e for e in lib if want and any(k.startswith(want) for k in keys(e))]
+    # prefer the plain text form over tab/abbreviated/instrument-specific variants
+    hits.sort(key=lambda e: (not e["entityID"].endswith("Text"), len(e["name"])))
+    if len(hits) == 1 or (hits and len(hits[0]["name"]) < len(hits[1]["name"]) and hits[0]["entityID"].endswith("Text")):
+        return hits[0]
+    names = ", ".join(f"{e['name']} ({e['entityID']})" for e in hits[:8]) or "none"
+    raise ValueError(f"playing technique {value!r}: {'ambiguous' if hits else 'unknown'}; candidates: {names}")
+
+
+def confirmed() -> dict[str, dict]:
+    return {r["capability"]: r for r in _load(CONFIRMED)} if CONFIRMED.exists() else {}
+
+
+def status(capability: str) -> str:
+    return confirmed().get(capability, {}).get("status", "unconfirmed")
+
+
+def describe_commands(filter: str = "", limit: int = 60) -> list[dict]:
+    rx = re.compile(filter, re.IGNORECASE) if filter else None
+    out = []
+    for c in commands().values():
+        if rx and not (rx.search(c["name"]) or rx.search(c.get("display_name") or "")):
+            continue
+        params = {k: {kk: vv for kk, vv in v.items() if kk in ("required", "enum_values", "observed_values")}
+                  for k, v in c.get("parameters", {}).items()}
+        out.append({"name": c["name"], "display_name": c.get("display_name"), "parameters": params,
+                    **({"internal": True} if c.get("internal") else {})})
+        if len(out) >= limit:
+            break
+    return out
+
+
+def describe_enums(name: str) -> dict:
+    e = enums()
+    if name in e:
+        return {name: [v[0] for v in e[name]]}
+    rx = re.compile(name, re.IGNORECASE)
+    hits = {k: [v[0] for v in vals] for k, vals in e.items() if rx.search(k)}
+    return dict(list(hits.items())[:20])
+
+
+class CommandError(ValueError):
+    pass
+
+
+def validate(command: str) -> str:
+    """Check a `Namespace.Command?Param=value&...` string against the catalogue; returns it unchanged."""
+    name, _, query = command.partition("?")
+    c = commands().get(name)
+    if c is None:
+        close = [n for n in commands() if n.lower().startswith(name.lower().split(".")[0] + ".")][:10]
+        raise CommandError(f"unknown command {name!r}" + (f"; same namespace: {close}" if close else ""))
+    params = c.get("parameters", {})
+    for k, v in parse_qsl(query, keep_blank_values=True):
+        if params and k not in params and not c.get("internal"):
+            raise CommandError(f"{name} has no parameter {k!r}; parameters: {sorted(params)}")
+        allowed = params.get(k, {}).get("enum_values")
+        if allowed and v not in allowed:
+            raise CommandError(f"{name}: {k}={v!r} not in {allowed}")
+    missing = [k for k, v in params.items() if v.get("required") and f"{k}=" not in query]
+    if missing:
+        raise CommandError(f"{name} requires {missing}")
+    return command
+
+
+if __name__ == "__main__":
+    assert validate("NoteInput.SetArticulation?Value=kStaccato")
+    for bad in ("Nope.Command", "Edit.ChangeVoice?VoiceDirection=kSideways", "NoteInput.SetArticulation?Bogus=1"):
+        try:
+            validate(bad)
+            raise AssertionError(bad)
+        except CommandError:
+            pass
+    assert describe_enums("LogDuration")["LogDuration"][0] == "k256Note" or describe_enums("LogDuration")
+    assert property_info("kNoteVelocity")
+    print("catalog self-check ok", len(commands()), "commands")