chordsym 0.0.2__tar.gz

chordsym-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+# wads CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration comes from this repo's pyproject.toml [tool.wads.ci.*].
+# To customize the workflow itself (rare), replace this file with the
+# full inline template `wads/data/github_ci_uv.yml` from i2mint/wads.
+#
+# Pinning: `@master` floats with wads. If you need version stability for
+# a release-sensitive repo, change `@master` to a wads tag (e.g. `@0.2.15`;
+# tags have no `v` prefix). A stub whose `secrets:` block passes the JSON
+# transport (the default below) needs a tag from a release after 0.2.14 —
+# older tags don't declare that secret and GitHub then rejects the
+# workflow at parse time.
+# CI failure does not block a published release — it blocks the publish
+# step itself — so floating master is generally safe.
+#
+# Permissions: GitHub validates that the caller grants AT LEAST the
+# permissions any job in the called workflow requests — at workflow-parse
+# time, not at run-time, even if the job would be skipped via `if:`.
+# The reusable workflow needs:
+#   contents: write   for the publish job's version-bump push-back
+#                     and for the github-pages job's gh-pages branch push
+#   pages: write      for the github-pages job's REST API Pages config
+# Both default to `write` on org-account GITHUB_TOKEN and need to be
+# granted explicitly on personal-account callers (where the default is
+# read-only). No `id-token: write` needed — the publish-github-pages
+# action uses peaceiris/actions-gh-pages (branch-based) + REST API,
+# not the OIDC `actions/deploy-pages` flow.
+name: Continuous Integration
+# The TypeScript twin (ts/) has its own workflow (npm-ci-ts.yml); a change only there
+# does not re-run or re-release the Python package. The generated grammar file is the
+# exception: tests/test_grammar.py checks it against chordsym/_grammar.py.
+on:
+  push:
+    paths: ["**", "!ts/**", "ts/src/grammar.generated.ts", "!.github/workflows/npm-ci-ts.yml"]
+  pull_request:
+    paths: ["**", "!ts/**", "ts/src/grammar.generated.ts", "!.github/workflows/npm-ci-ts.yml"]
+jobs:
+  ci:
+    uses: i2mint/wads/.github/workflows/uv-ci.yml@master
+    permissions:
+      contents: write
+      pages: write
+    # Transport (NAMED, legacy): explicitly passes only the secrets
+    # listed below (PYPI_PASSWORD + those declared in
+    # [tool.wads.ci.env]). Every name must be in the frozen wads
+    # superset (wads/ci_secrets.py) or GitHub rejects the workflow
+    # at parse time. The default JSON transport has no such limit;
+    # regenerate with `wads-migrate ci-to-stub` to switch.
+    secrets:
+      PYPI_PASSWORD: ${{ secrets.PYPI_PASSWORD }}

chordsym-0.0.2/.github/workflows/npm-ci-ts.yml

@@ -0,0 +1,42 @@
+# wads NPM CI — calls the reusable workflow hosted in i2mint/wads.
+#
+# All configuration lives in ts/package.json under the "wads"
+# key (wads.ci.*). This workflow only runs when the JS subdirectory changes,
+# so it never collides with the Python ci.yml.
+#
+# Publishing to npm is OPT-IN: set wads.ci.publish.enabled=true in package.json
+# and include the marker (default "[publish-npm]") in your commit message.
+# Publishing uses npm trusted publishing (OIDC); there is no NPM_TOKEN secret.
+# On npmjs.com: package -> Settings -> Trusted Publisher -> GitHub Actions, with
+# this repo and THIS file's name (npm-ci-ts.yml), or run
+#   npm trust github <pkg> --file npm-ci-ts.yml --repo <owner>/<repo> --allow-publish -y
+# The package must exist on npm first: publish the very first version locally.
+#
+# On-demand CI (opt-in, mirrors [tool.wads.ci.trigger] on the Python side):
+# set wads.ci.trigger.mode="on-demand" in package.json and the reusable
+# workflow's validate/publish jobs run only when the commit SUBJECT contains
+# wads.ci.trigger.runCiMarker (default "[run ci]"), or the run is a manual
+# `gh workflow run npm-ci-ts.yml --ref <branch>` (always allowed).
+# To do locally what CI would have done: `npm run ci-local` (lint, test,
+# build — add that script to package.json if it isn't there already).
+name: NPM CI (ts)
+# fixtures/ holds the golden cases both twins run, so a change there re-runs this one too.
+on:
+  push:
+    paths:
+      - "ts/**"
+      - "fixtures/**"
+      - ".github/workflows/npm-ci-ts.yml"
+  pull_request:
+    paths:
+      - "ts/**"
+      - "fixtures/**"
+      - ".github/workflows/npm-ci-ts.yml"
+jobs:
+  npm-ci:
+    uses: i2mint/wads/.github/workflows/npm-ci.yml@master
+    permissions:
+      contents: read
+      id-token: write # npm provenance / OIDC trusted publishing
+    with:
+      package-dir: ts

chordsym-0.0.2/.gitignore

@@ -0,0 +1,129 @@
+.claude/handoffs/
+.claude/scratch/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+
+.DS_Store
+# C extensions
+*.so
+
+# TLS certificates
+## Ignore all PEM files anywhere
+*.pem
+## Also ignore any certs directory
+certs/
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+_build
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/*
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm
+.idea
+__pycache__/
+*.egg-info/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+
+# Node / the TypeScript twin (ts/)
+node_modules/

chordsym-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thor Whalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chordsym-0.0.2/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: chordsym
+Version: 0.0.2
+Summary: Chord symbols without dependencies: parse, pitch classes, key estimation, transposition
+Project-URL: Homepage, https://github.com/thorwhalen/chordsym
+Project-URL: Repository, https://github.com/thorwhalen/chordsym
+Project-URL: Documentation, https://thorwhalen.github.io/chordsym
+Author: Thor Whalen
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chords,harmony,music,transposition
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# chordsym
+
+Chord symbols without dependencies (standard library only): is this token a chord, which root and quality, which pitch classes, which key does a song's chord list suggest, and how do the chords read moved by N semitones.
+
+```python
+>>> from chordsym import parse_chord, chord_tones, transpose_chord, transposition_table, estimate_key
+>>> parse_chord("F#m7"), chord_tones("Cmaj7")
+((6, 'minor'), (0, 4, 7, 11))
+>>> transpose_chord("C/E", 3, flats=True)
+'Eb/G'
+>>> transposition_table(["G", "D", "Em", "C"], 3)["chords"]
+{'G': 'Bb', 'D': 'F', 'Em': 'Gm', 'C': 'Eb'}
+```
+
+It reads the spellings found in scraped chord charts (`C6/9`, `Bm5-/7`, Brazilian `7M`, `E7(#9)`, `D/F#`), not only textbook ones. Pitch classes are ints 0-11 (C = 0).
+
+## In the browser: the TypeScript twin
+
+The same functions ship to npm as `chordsym` (in `ts/`), with camelCase names and keyword arguments as an options object:
+
+```ts
+import { parseChord, transposeChord, estimateKey } from "chordsym";
+
+parseChord("Am7");                         // [9, "minor"]
+transposeChord("C/E", 3, { flats: true }); // "Eb/G"
+estimateKey(["Am", "Dm", "E7"]);           // { tonic: 9, minor: true }
+```
+
+The two are kept identical by construction, not by care:
+
+- **One grammar.** Every regular expression and table lives in `chordsym/_grammar.py`, written in the subset of regex syntax that means the same in Python and JavaScript (no `\d`, `\s`, `\w`, `\b`). `python -m chordsym._codegen` writes it to `ts/src/grammar.generated.ts`, and a test fails if that file is stale.
+- **One set of golden cases.** `fixtures/cases.json` holds about 1,500 calls with their expected results, errors included (`ValueError` in Python is `RangeError` in TypeScript). pytest and vitest both run every one and compare them as JSON text, so order matters. To add a case, append it and run `python -m chordsym._fixtures`, which records the Python results; review the diff, since a changed expectation is a behaviour change on both sides.
+- **A wide net before releases.** `python scripts/twin_differential.py` (after `cd ts && npm run build`) runs about 75,000 generated chord spellings and 3,000 songs through both and reports any difference.
+
+Where the languages differ, the TypeScript side says so in its types: `transpositionTable(...).chords` is a `Map` (a plain object would reorder integer-like keys), and a `Key` is a plain `{ tonic, minor }` object checked by every function that takes one (`keyEquals` compares two).
+
+Versions: an npm release carries the version of the Python release it was cut from (lockstep at release points, so `chordsym@X.Y.Z` on npm and PyPI are the same behaviour).
+
+Seeded from songleaf (thorwhalen/songleaf#31). Planned: dialects (Harte, Chordonomicon, Nashville/Roman) as strategies; pychord and music21 as test oracles only.

chordsym-0.0.2/README.md

@@ -0,0 +1,39 @@
+# chordsym
+
+Chord symbols without dependencies (standard library only): is this token a chord, which root and quality, which pitch classes, which key does a song's chord list suggest, and how do the chords read moved by N semitones.
+
+```python
+>>> from chordsym import parse_chord, chord_tones, transpose_chord, transposition_table, estimate_key
+>>> parse_chord("F#m7"), chord_tones("Cmaj7")
+((6, 'minor'), (0, 4, 7, 11))
+>>> transpose_chord("C/E", 3, flats=True)
+'Eb/G'
+>>> transposition_table(["G", "D", "Em", "C"], 3)["chords"]
+{'G': 'Bb', 'D': 'F', 'Em': 'Gm', 'C': 'Eb'}
+```
+
+It reads the spellings found in scraped chord charts (`C6/9`, `Bm5-/7`, Brazilian `7M`, `E7(#9)`, `D/F#`), not only textbook ones. Pitch classes are ints 0-11 (C = 0).
+
+## In the browser: the TypeScript twin
+
+The same functions ship to npm as `chordsym` (in `ts/`), with camelCase names and keyword arguments as an options object:
+
+```ts
+import { parseChord, transposeChord, estimateKey } from "chordsym";
+
+parseChord("Am7");                         // [9, "minor"]
+transposeChord("C/E", 3, { flats: true }); // "Eb/G"
+estimateKey(["Am", "Dm", "E7"]);           // { tonic: 9, minor: true }
+```
+
+The two are kept identical by construction, not by care:
+
+- **One grammar.** Every regular expression and table lives in `chordsym/_grammar.py`, written in the subset of regex syntax that means the same in Python and JavaScript (no `\d`, `\s`, `\w`, `\b`). `python -m chordsym._codegen` writes it to `ts/src/grammar.generated.ts`, and a test fails if that file is stale.
+- **One set of golden cases.** `fixtures/cases.json` holds about 1,500 calls with their expected results, errors included (`ValueError` in Python is `RangeError` in TypeScript). pytest and vitest both run every one and compare them as JSON text, so order matters. To add a case, append it and run `python -m chordsym._fixtures`, which records the Python results; review the diff, since a changed expectation is a behaviour change on both sides.
+- **A wide net before releases.** `python scripts/twin_differential.py` (after `cd ts && npm run build`) runs about 75,000 generated chord spellings and 3,000 songs through both and reports any difference.
+
+Where the languages differ, the TypeScript side says so in its types: `transpositionTable(...).chords` is a `Map` (a plain object would reorder integer-like keys), and a `Key` is a plain `{ tonic, minor }` object checked by every function that takes one (`keyEquals` compares two).
+
+Versions: an npm release carries the version of the Python release it was cut from (lockstep at release points, so `chordsym@X.Y.Z` on npm and PyPI are the same behaviour).
+
+Seeded from songleaf (thorwhalen/songleaf#31). Planned: dialects (Harte, Chordonomicon, Nashville/Roman) as strategies; pychord and music21 as test oracles only.

chordsym-0.0.2/chordsym/__init__.py

@@ -0,0 +1,28 @@
+"""chordsym: chord symbols without dependencies — parse, pitch classes, keys, transposition.
+
+>>> from chordsym import parse_chord, transpose_chord, estimate_key
+>>> parse_chord("Am7"), transpose_chord("Am7", 2), estimate_key(["Am", "Dm", "E7"])
+((9, 'minor'), 'Bm7', Key(tonic=9, minor=True))
+"""
+
+from chordsym.keys import Key, chord_function, estimate_key
+from chordsym.parse import chord_tones, is_chord_token, parse_chord
+from chordsym.transpose import (
+    key_name,
+    transpose_chord,
+    transposition_table,
+    uses_flats,
+)
+
+__all__ = [
+    "Key",
+    "chord_function",
+    "chord_tones",
+    "estimate_key",
+    "is_chord_token",
+    "key_name",
+    "parse_chord",
+    "transpose_chord",
+    "transposition_table",
+    "uses_flats",
+]

chordsym-0.0.2/chordsym/_codegen.py

@@ -0,0 +1,72 @@
+"""Write the shared grammar (``chordsym._grammar``) as the TypeScript twin's ``grammar.generated.ts``.
+
+Every public UPPER_CASE name in ``_grammar`` is emitted (as a JSON literal, ``as const``),
+so a table added on the Python side reaches TypeScript without touching this module. It
+also emits ``WHITESPACE``, the code points Python's ``str.isspace`` accepts, which the
+TypeScript ``strip`` uses and against which the vitest suite checks the ``WS`` class.
+
+Run ``python -m chordsym._codegen`` after editing ``_grammar.py``; ``tests/test_grammar.py``
+fails while the committed TypeScript file differs from what this module renders.
+
+>>> 'export const PATTERNS' in render_ts() and 'export const WHITESPACE' in render_ts()
+True
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+from chordsym import _grammar
+
+#: The repository root (where ``ts/`` lives, next to the package).
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+#: Where the TypeScript twin keeps the generated grammar, relative to the repository root.
+TS_GRAMMAR_PATH = Path("ts") / "src" / "grammar.generated.ts"
+
+_HEADER = """\
+// GENERATED by `python -m chordsym._codegen` from chordsym/_grammar.py. Do not edit:
+// edit the Python module and regenerate (tests/test_grammar.py checks this file is current).
+"""
+
+
+def grammar_names() -> list[str]:
+    """The names ``_grammar`` shares: every public UPPER_CASE module attribute."""
+    return [n for n in vars(_grammar) if n.isupper() and not n.startswith("_")]
+
+
+def whitespace_code_points() -> list[int]:
+    """Every code point ``str.isspace`` accepts (what ``str.strip()`` removes)."""
+    return [c for c in range(sys.maxunicode + 1) if chr(c).isspace()]
+
+
+def _jsonable(value):
+    if isinstance(value, (tuple, list)):
+        return [_jsonable(v) for v in value]
+    if isinstance(value, dict):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    return value
+
+
+def render_ts() -> str:
+    """The TypeScript source of the shared grammar, exactly as it should be committed."""
+    shared = {name: getattr(_grammar, name) for name in grammar_names()}
+    shared["WHITESPACE"] = whitespace_code_points()
+    lines = [_HEADER]
+    for name, value in shared.items():
+        literal = json.dumps(_jsonable(value), ensure_ascii=False)
+        lines.append(f"export const {name} = {literal} as const;")
+    return "\n".join(lines) + "\n"
+
+
+def write_ts(root: Path | str = REPO_ROOT) -> Path:
+    """Write :func:`render_ts` to ``<root>/ts/src/grammar.generated.ts``; return the path."""
+    path = Path(root) / TS_GRAMMAR_PATH
+    path.write_text(render_ts(), encoding="utf-8")
+    return path
+
+
+if __name__ == "__main__":
+    print(write_ts())

chordsym-0.0.2/chordsym/_fixtures.py

@@ -0,0 +1,149 @@
+"""Run and record the golden cases in ``fixtures/cases.json``, the behaviour both twins must share.
+
+A case is ``{"fn": <public function name>, "args": [...], "kwargs": {...}, "expected": ...}``
+in JSON form:
+
+- tuples are lists; a :class:`~chordsym.Key` is ``{"tonic": int, "minor": bool}``;
+- an open mapping in a result (``transposition_table(...)["chords"]``) is a list of
+  ``[key, value]`` pairs, because its order is part of the contract and a JSON object's
+  is not (JavaScript moves integer-like keys first);
+- an exception is ``{"$raises": "ValueError"}`` (TypeScript: ``RangeError``) or
+  ``{"$raises": "TypeError"}``;
+- ``kwargs`` may only name keyword-only parameters, which the TypeScript twin takes as a
+  trailing options object.
+
+The file's ``functions`` list is the public API (``chordsym.__all__`` minus classes); both
+test suites check that they cover exactly it. Results are compared as JSON text, so order
+matters everywhere.
+
+To add a case, append it with any ``expected`` and run ``python -m chordsym._fixtures``: it
+rewrites every ``expected`` from the Python implementation, so review the diff (a changed
+expectation is a behaviour change on both sides).
+
+>>> run_case({"fn": "transpose_chord", "args": ["C/E", 3], "kwargs": {"flats": True}})
+'Eb/G'
+>>> run_case({"fn": "estimate_key", "args": [["Am", "Dm", "E7"]]})
+{'tonic': 9, 'minor': True}
+>>> run_case({"fn": "key_name", "args": [{"tonic": 12, "minor": False}]})
+{'$raises': 'ValueError'}
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from pathlib import Path
+
+import chordsym
+from chordsym.keys import Key
+
+#: The repository root (where ``fixtures/`` and ``ts/`` live, next to the package).
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+#: The golden cases, relative to the repository root.
+CASES_PATH = Path("fixtures") / "cases.json"
+
+#: The exceptions a case may expect; the TypeScript twin throws the mapped JS error.
+RAISES = (ValueError, TypeError)
+
+
+def public_functions() -> tuple[str, ...]:
+    """The functions of the public API (``chordsym.__all__``, classes excluded)."""
+    return tuple(
+        name for name in chordsym.__all__ if inspect.isfunction(getattr(chordsym, name))
+    )
+
+
+#: Per-function result encoders, for results whose JSON form needs more than to_json.
+_ENCODERS = {
+    "transposition_table": lambda r: {
+        **r,
+        "chords": [list(kv) for kv in r["chords"].items()],
+    },
+}
+
+
+def _decode(value):
+    if isinstance(value, dict) and set(value) == {"tonic", "minor"}:
+        return Key(value["tonic"], value["minor"])
+    if isinstance(value, list):
+        return [_decode(v) for v in value]
+    return value
+
+
+def to_json(value):
+    """``value`` in the JSON form cases use (tuples as lists, Key as a dict)."""
+    if isinstance(value, Key):
+        return {"tonic": value.tonic, "minor": value.minor}
+    if isinstance(value, (tuple, list)):
+        return [to_json(v) for v in value]
+    if isinstance(value, dict):
+        return {k: to_json(v) for k, v in value.items()}
+    return value
+
+
+def _check_kwargs(name: str, func, kwargs: dict) -> None:
+    params = inspect.signature(func).parameters
+    for kw in kwargs:
+        if kw not in params or params[kw].kind is not inspect.Parameter.KEYWORD_ONLY:
+            raise ValueError(
+                f"Case for {name}: {kw!r} is not a keyword-only parameter; pass it in args"
+            )
+
+
+def run_case(case: dict):
+    """Call the case's function on its arguments; return the result in JSON form."""
+    name = case["fn"]
+    if name not in public_functions():
+        raise ValueError(
+            f"Unknown function in case: {name!r}; one of {public_functions()}"
+        )
+    func = getattr(chordsym, name)
+    kwargs = case.get("kwargs", {})
+    _check_kwargs(name, func, kwargs)
+    try:
+        args = [_decode(a) for a in case.get("args", [])]
+        result = func(*args, **{k: _decode(v) for k, v in kwargs.items()})
+    except RAISES as error:
+        return {"$raises": type(error).__name__}
+    encoded = to_json(result)
+    return _ENCODERS[name](encoded) if name in _ENCODERS else encoded
+
+
+def same(result, expected) -> bool:
+    """Whether two JSON values are equal, order included (what both test suites check)."""
+    return json.dumps(result, ensure_ascii=False) == json.dumps(
+        expected, ensure_ascii=False
+    )
+
+
+def load(root: Path | str = REPO_ROOT) -> dict:
+    """The parsed ``<root>/fixtures/cases.json``."""
+    return json.loads((Path(root) / CASES_PATH).read_text(encoding="utf-8"))
+
+
+def record(root: Path | str = REPO_ROOT) -> Path:
+    """Rewrite every case's ``expected`` (and the ``functions`` list) from Python."""
+    path = Path(root) / CASES_PATH
+    data = load(root)
+    data["functions"] = list(public_functions())
+    for case in data["cases"]:
+        case["expected"] = run_case(case)
+    path.write_text(dumps(data), encoding="utf-8")
+    return path
+
+
+def dumps(data: dict) -> str:
+    """The cases file's text: one case per line, so a diff shows exactly which cases changed."""
+
+    def line(obj) -> str:
+        return json.dumps(obj, ensure_ascii=False)
+
+    head = {k: v for k, v in data.items() if k != "cases"}
+    rows = ",\n".join("  " + line(case) for case in data["cases"])
+    fields = "".join(f"\n {line(k)}: {line(v)}," for k, v in head.items())
+    return "{" + fields + '\n "cases": [\n' + rows + "\n ]\n}\n"
+
+
+if __name__ == "__main__":
+    print(record())