jmesway 0.1.0__tar.gz

jmesway-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alpine
+
+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.

jmesway-0.1.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: jmesway
+Version: 0.1.0
+Summary: JMESPath workflow management tool
+Keywords: 
+Author: alpine
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Dist: jmespath>=1.1.0
+Requires-Dist: json5>=0.15.0 ; extra == 'cli'
+Requires-Dist: rich>=15.0.0 ; extra == 'cli'
+Requires-Dist: watchfiles>=1.2.0 ; extra == 'cli'
+Requires-Python: >=3.10
+Provides-Extra: cli
+Description-Content-Type: text/markdown
+
+# Jmesway
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+> ⚠️ This is an early-stage personal project. The API and file format may still change.
+
+Write JSON5 input/output examples and JMESPath expressions in a single Markdown
+file (`.roadmap.md`), and get a spec, a test case, and a JSON → JSON
+transformation, all in one place.
+

jmesway-0.1.0/README_PYPI.md

@@ -0,0 +1,10 @@
+# Jmesway
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+> ⚠️ This is an early-stage personal project. The API and file format may still change.
+
+Write JSON5 input/output examples and JMESPath expressions in a single Markdown
+file (`.roadmap.md`), and get a spec, a test case, and a JSON → JSON
+transformation, all in one place.
+

jmesway-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "jmesway"
+version = "0.1.0"
+description = "JMESPath workflow management tool"
+readme = "README_PYPI.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing",
+]
+requires-python = ">=3.10"
+dependencies = ["jmespath>=1.1.0"]
+
+[[project.authors]]
+name = "alpine"
+
+[project.optional-dependencies]
+cli = [
+    "json5>=0.15.0",
+    "rich>=15.0.0",
+    "watchfiles>=1.2.0",
+]
+
+[project.scripts]
+jmesway = "jmesway:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jmesway[cli]",
+    "pytest>=9.1.1",
+    "ruff>=0.16.7",
+]

jmesway-0.1.0/pyproject.toml.orig

@@ -0,0 +1,48 @@
+[project]
+name = "jmesway"
+version = "0.1.0"
+description = "JMESPath workflow management tool"
+readme = "README_PYPI.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "alpine" },
+]
+keywords = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "jmespath>=1.1.0",
+]
+
+[project.optional-dependencies]
+cli = [
+    "json5>=0.15.0",
+    "rich>=15.0.0",
+    "watchfiles>=1.2.0",
+]
+
+[project.scripts]
+jmesway = "jmesway:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jmesway[cli]",
+    "pytest>=9.1.1",
+    "ruff>=0.16.7",
+]

jmesway-0.1.0/src/jmesway/__init__.py

@@ -0,0 +1,18 @@
+"""``main`` は CLI 用の遅延インポート。ランタイム利用（例: ``jmesway.jmespath_transform``）は
+`jmespath` のみで完結し、`json5`/`rich`/`watchfiles`（``cli`` extra）を要求しない。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["main"]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "main":
+        from .cli import main
+
+        return main
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+

jmesway-0.1.0/src/jmesway/cli.py

@@ -0,0 +1,240 @@
+"""jmesway CLI: `.roadmap.md` の自己検証・単発実行・Python コード生成。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.syntax import Syntax
+from watchfiles import watch
+
+from .roadmap import CaseVerificationError, RoadmapDocument
+from .transpiler import generate_source, output_path_for
+
+_out = Console()
+_err = Console(stderr=True)
+
+
+def _load_json_input(source: str) -> Any:
+    """``-`` なら標準入力、それ以外はファイルパスとして JSON を読み込む。"""
+    if source == "-":
+        return json.loads(sys.stdin.read())
+    return json.loads(Path(source).read_text(encoding="utf-8"))
+
+
+def _json_panel(title: str, value: Any, border_style: str) -> Panel:
+    body = json.dumps(value, ensure_ascii=False, indent=2)
+    return Panel(
+        Syntax(body, "json", background_color="default"),
+        title=title,
+        title_align="left",
+        border_style=border_style,
+        expand=False,
+    )
+
+
+def _print_verification_error(path: Path, error: CaseVerificationError) -> None:
+    """どの CASE / JMESPath 式が失敗したかを、コード部分をパネルとして分離して表示する。"""
+    case = error.case
+    _err.print(f"[bold red]NG[/bold red] {path}")
+    _err.print(f"  [bold]CASE:[/bold] {case.title}  (line {case.line})")
+    _err.print(
+        Panel(
+            Syntax(error.expression, "text", background_color="default", word_wrap=True),
+            title=f"JMESPATH (step {error.step_index})",
+            title_align="left",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+    _err.print(_json_panel("expected", error.expected, "green"))
+    _err.print(_json_panel("actual", error.actual, "red"))
+
+
+def _error_to_dict(error: Exception) -> dict[str, Any]:
+    """エラーを AI / ツール向けの JSON として機械判読可能な形に分解する。"""
+    if isinstance(error, CaseVerificationError):
+        case = error.case
+        return {
+            "error_type": "case_verification",
+            "case": {"title": case.title, "line": case.line},
+            "step_index": error.step_index,
+            "expression": error.expression,
+            "expected": error.expected,
+            "actual": error.actual,
+        }
+    return {"error_type": "parse", "message": str(error)}
+
+
+def _print_json(result: dict[str, Any]) -> None:
+    print(json.dumps(result, ensure_ascii=False))
+
+
+def _check_once(files: Sequence[str], *, as_json: bool = False) -> int:
+    exit_code = 0
+    for file in files:
+        path = Path(file)
+        try:
+            doc = RoadmapDocument.load(path)
+            doc.verify_all()
+        except (ValueError, AssertionError) as e:
+            exit_code = 1
+            if as_json:
+                _print_json({"path": str(path), "status": "ng", **_error_to_dict(e)})
+            elif isinstance(e, CaseVerificationError):
+                _print_verification_error(path, e)
+            else:
+                _err.print(f"[bold red]NG[/bold red] {path}: {e}")
+            continue
+        if as_json:
+            _print_json({"path": str(path), "status": "ok", "cases": len(doc.cases)})
+        else:
+            _out.print(f"[bold green]OK[/bold green] {path}: {len(doc.cases)} case(s) verified")
+    return exit_code
+
+
+def _check_live(files: Sequence[str], *, as_json: bool = False) -> int:
+    """指定ファイルの変更を検知するたびに再検証する（Ctrl+C で終了）。"""
+    paths = [Path(file) for file in files]
+    _check_once(files, as_json=as_json)
+    if not as_json:
+        _out.print("[dim]--live: watching for changes (Ctrl+C to stop)[/dim]")
+    try:
+        for _ in watch(*paths):
+            _check_once(files, as_json=as_json)
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    if args.live:
+        return _check_live(args.files, as_json=args.json)
+    return _check_once(args.files, as_json=args.json)
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    doc = RoadmapDocument.load(args.file)
+    try:
+        pipeline = doc.pipeline(args.pipeline)
+    except KeyError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    data = _load_json_input(args.input)
+    result = pipeline.transform(data)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _cmd_build(args: argparse.Namespace) -> int:
+    if args.live:
+        return _build_live(args.files, check=args.check, as_json=args.json)
+    return _build_once(args.files, check=args.check, as_json=args.json)
+
+
+def _build_once(files: Sequence[str], *, check: bool, as_json: bool = False) -> int:
+    exit_code = 0
+    for file in files:
+        source_path = Path(file)
+        doc = RoadmapDocument.load(source_path)
+
+        try:
+            doc.verify_all()
+        except AssertionError as e:
+            exit_code = 1
+            if as_json:
+                _print_json({"path": str(source_path), "status": "ng", **_error_to_dict(e)})
+            elif isinstance(e, CaseVerificationError):
+                _print_verification_error(source_path, e)
+            else:
+                _err.print(f"[bold red]NG[/bold red] {source_path}: {e}")
+            continue
+
+        out_path = output_path_for(source_path)
+        generated = generate_source(doc, source_path)
+
+        if check:
+            existing = out_path.read_text(encoding="utf-8") if out_path.exists() else None
+            if existing != generated:
+                exit_code = 1
+                if as_json:
+                    _print_json(
+                        {"path": str(out_path), "status": "ng", "error_type": "drift", "message": "needs regeneration"}
+                    )
+                else:
+                    _err.print(f"[bold red]NG[/bold red] {out_path}: needs regeneration (run 'jmesway build')")
+            elif as_json:
+                _print_json({"path": str(out_path), "status": "ok", "action": "up_to_date"})
+            else:
+                _out.print(f"[bold green]OK[/bold green] {out_path}: up to date")
+            continue
+
+        out_path.write_text(generated, encoding="utf-8")
+        if as_json:
+            _print_json({"path": str(out_path), "status": "ok", "action": "generated"})
+        else:
+            _out.print(f"[bold green]generated[/bold green] {out_path}")
+    return exit_code
+
+
+def _build_live(files: Sequence[str], *, check: bool, as_json: bool = False) -> int:
+    """指定ファイルの変更を検知するたびに再 build する（Ctrl+C で終了）。
+
+    build 忘れ（roadmap.md を編集したのに .py を再生成していない）を防ぐのが狙い。
+    """
+    paths = [Path(file) for file in files]
+    _build_once(files, check=check, as_json=as_json)
+    if not as_json:
+        _out.print("[dim]--live: watching for changes (Ctrl+C to stop)[/dim]")
+    try:
+        for _ in watch(*paths):
+            _build_once(files, check=check, as_json=as_json)
+    except KeyboardInterrupt:
+        pass
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="jmesway", description="jmesway: JSON to JSON データ変換ユーティリティ")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    check_parser = subparsers.add_parser("check", help="roadmap.md の IN/OUT を自己検証する")
+    check_parser.add_argument("files", nargs="+", help=".roadmap.md ファイル")
+    check_parser.add_argument(
+        "--live", action="store_true", help="ファイル変更を検知するたびに再検証し続ける（Ctrl+C で終了）"
+    )
+    check_parser.add_argument(
+        "--json", action="store_true", help="人間向けの装飾表示の代わりに、1行1JSONの機械可読な結果を出力する"
+    )
+    check_parser.set_defaults(func=_cmd_check)
+
+    run_parser = subparsers.add_parser("run", help="指定したパイプラインを単発実行する")
+    run_parser.add_argument("file", help=".roadmap.md ファイル")
+    run_parser.add_argument("--pipeline", required=True, help="実行するパイプライン名")
+    run_parser.add_argument("--in", dest="input", required=True, help="入力 JSON ファイル（'-' で標準入力）")
+    run_parser.set_defaults(func=_cmd_run)
+
+    build_parser = subparsers.add_parser("build", help="roadmap.md から .py を事前生成する")
+    build_parser.add_argument("files", nargs="+", help=".roadmap.md ファイル")
+    build_parser.add_argument("--check", action="store_true", help="生成物との不整合を検知するのみ（書き込まない）")
+    build_parser.add_argument(
+        "--live", action="store_true", help="ファイル変更を検知するたびに再 build し続ける（Ctrl+C で終了）"
+    )
+    build_parser.add_argument(
+        "--json", action="store_true", help="人間向けの装飾表示の代わりに、1行1JSONの機械可読な結果を出力する"
+    )
+    build_parser.set_defaults(func=_cmd_build)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    sys.exit(args.func(args))

jmesway-0.1.0/src/jmesway/jmespath_transform.py

@@ -0,0 +1,281 @@
+"""汎用 JMESPath 変換モジュール。
+
+特徴:
+- 任意のオブジェクトを自動的に dict 風にラップ（呼び出し側での明示的ラップ不要）
+- カスタム関数は型ヒント付き関数として引数で渡す形式（クラス定義不要）
+- 式はコンパイルキャッシュによる再パース抑止
+- アドオン関数ごとにキャッシュして再利用
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import types as _builtins
+from collections.abc import Callable
+from datetime import date, datetime
+from decimal import Decimal
+from functools import lru_cache
+from logging import getLogger
+from typing import Any, Union, get_args, get_origin, get_type_hints
+
+import jmespath
+from jmespath import functions
+
+logger = getLogger(__name__)
+
+
+class _AsDict:
+    """非 dict オブジェクトを jmespath で属性アクセスできるよう dict 風に包む（内部用）。
+
+    jmespath は ``value[key]`` (``__getitem__``) でフィールドアクセスするため、
+    ``__getitem__`` / ``get`` を実装することで ``obj.attr`` のような dot 記法が使える。
+    返り値は ``_wrap()`` を通して再帰的に処理されるため、ネストしたオブジェクトも透過的に扱える。
+    """
+
+    def __init__(self, obj: Any) -> None:
+        self._obj = obj
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return _wrap(getattr(self._obj, key, default))
+
+    def __getitem__(self, key: str) -> Any:
+        return _wrap(getattr(self._obj, key))
+
+    def __contains__(self, key: str) -> bool:
+        return hasattr(self._obj, key)
+
+
+def _wrap(data: Any) -> Any:
+    """任意のデータを JMESPath 評価用にラップする。
+
+    - ``None`` / プリミティブ型（str, int, float, bool）: そのまま返す
+    - ``dict``: 値を再帰的に処理した新しい dict を返す
+    - ``list``: 要素を再帰的に処理した新しい list を返す
+    - その他のオブジェクト: ``_AsDict`` でラップして返す
+    """
+    if data is None or isinstance(data, (str, int, float, bool, date, datetime, Decimal)):
+        return data
+    if isinstance(data, dict):
+        return {k: _wrap(v) for k, v in data.items()}
+    if isinstance(data, list):
+        return [_wrap(item) for item in data]
+    return _AsDict(data)
+
+
+_JMESPATH_TYPE_MAP: dict[type, str] = {
+    str: "string",
+    int: "number",
+    float: "number",
+    bool: "boolean",
+    dict: "object",
+    list: "array",
+    type(None): "null",
+}
+
+
+def _hint_to_jmespath_spec(hint: Any) -> dict:
+    """Python 型ヒントを jmespath の引数型仕様 dict に変換する。
+
+    - str / int / float / bool / dict / list / None → 対応する jmespath type
+    - Union[X, Y] / X | Y → 複数型のリスト
+    - Any・未対応型 → {"types": []}（型チェック無効）
+    """
+    if hint is Any:
+        return {"types": []}
+
+    origin = get_origin(hint)
+    is_union = origin is Union
+    if not is_union and hasattr(_builtins, "UnionType"):
+        is_union = isinstance(hint, _builtins.UnionType)
+
+    if is_union:
+        jmespath_types = []
+        for arg in get_args(hint):
+            jt = _JMESPATH_TYPE_MAP.get(arg)
+            if jt is None:
+                return {"types": []}  # 不明な型が含まれる場合は無制限
+            jmespath_types.append(jt)
+        return {"types": jmespath_types}
+
+    jt = _JMESPATH_TYPE_MAP.get(hint)
+    return {"types": [jt]} if jt is not None else {"types": []}
+
+
+def _auto_signature(cls: type) -> type:
+    """``_func_*`` メソッドの型ヒントから signature を自動生成するクラスデコレータ（内部用）。
+
+    クラス自身に定義された ``_func_*`` メソッドのうち、まだ ``.signature`` 属性を持たないものに対して
+    引数の型ヒントから ``_hint_to_jmespath_spec()`` で仕様を生成し付与する。
+    """
+    for name, method in vars(cls).items():
+        if not name.startswith("_func_") or not callable(method) or hasattr(method, "signature"):
+            continue
+        try:
+            hints = get_type_hints(method)
+        except (NameError, TypeError):
+            hints = {}
+        params = [p for p in inspect.signature(method).parameters if p != "self"]
+        method.signature = tuple(_hint_to_jmespath_spec(hints.get(p, Any)) for p in params)
+    return cls
+
+
+@_auto_signature
+class DefaultFunctions(functions.Functions):
+    """transform() の全呼び出しで自動的に有効になるデフォルトカスタム関数。
+
+    アドオンクラスからも継承して拡張できる。
+    ``@_auto_signature`` により ``_func_*`` メソッドの型ヒントから signature が自動生成される。
+    """
+
+    # --- 日付系 ---
+    def _func_format_date(self, d: date | datetime | str, fmt: str) -> str:
+        """date/datetime オブジェクト、または ISO 8601 文字列を指定フォーマットで文字列化する。
+
+        文字列を渡した場合は ISO 8601 として解釈してから変換する（date/datetime を経由し、
+        出力に Python 型が残らないようにするため、この関数だけで完結させる設計）。
+
+        例: format_date(ordered_at, '%Y%m') -> '202503'
+        """
+        if isinstance(d, str):
+            d = datetime.fromisoformat(d)
+        return d.strftime(fmt)
+
+    # --- 文字列系 ---
+    def _func_upper(self, s: str) -> str:
+        """文字列を大文字に変換する。"""
+        return s.upper()
+
+    def _func_lower(self, s: str) -> str:
+        """文字列を小文字に変換する。"""
+        return s.lower()
+
+    def _func_strip(self, s: str | None) -> str:
+        """文字列の前後の空白を除去する。null は空文字として扱う。"""
+        return (s or "").strip()
+
+    def _func_replace(self, s: str | None, old: str, new: str) -> str:
+        """文字列中の old を new に置換する。null は空文字として扱う。"""
+        return (s or "").replace(old, new)
+
+    def _func_split(self, s: str, sep: str) -> list[str]:
+        """文字列を sep で分割してリストに変換する。"""
+        return s.split(sep)
+
+    # --- 値マッピング系 ---
+    def _func_match(self, value: Any, mapping: dict, default: Any) -> Any:
+        """value を mapping の key と照合し対応する値を返す。一致しなければ default を返す。"""
+        return mapping.get(value, default)
+
+    def _func_coalesce(self, *values: Any) -> Any:
+        """先頭から順に null でない最初の値を返す（SQL の COALESCE 相当）。すべて null なら null。
+
+        ``||`` は JMESPath の falsy（``false``/``null``/``""``/``[]``/``{}``）でフォールバックするが、
+        こちらは ``null`` のみを対象にするため、``0`` や ``false``、``""`` を正当な値として残せる。
+        """
+        return next((v for v in values if v is not None), None)
+
+    _func_coalesce.signature = ({"types": [], "variadic": True},)
+
+    # --- JSON 変換 ---
+    def _func_to_json_string(self, data: Any) -> str:
+        """任意のデータを JSON 文字列へ変換する。ensure_ascii=False で日本語はそのまま出力。"""
+        return json.dumps(data, ensure_ascii=False)
+
+
+@lru_cache(maxsize=1024)
+def _func_to_addon_class(fn: Callable) -> type:
+    """型ヒント付き関数を jmespath アドオンクラスに変換する（結果はキャッシュされる）。
+
+    各引数の型ヒントから ``@functions.signature()`` 相当の宣言を自動生成する。
+    型ヒントのない引数・未対応型は ``{"types": []}``（型チェック無効）として扱う。
+    ``self`` 引数は不要（通常の関数として定義すればよい）。
+
+    Args:
+        fn: 型ヒント付きの関数
+
+    Returns:
+        ``functions.Functions`` のサブクラス
+    """
+    try:
+        hints = get_type_hints(fn)
+    except (NameError, TypeError):
+        hints = {}
+
+    params = list(inspect.signature(fn).parameters.keys())
+    specs = [_hint_to_jmespath_spec(hints.get(p, Any)) for p in params]
+
+    def _method(self, *args):
+        return fn(*args)
+
+    _method.signature = tuple(specs)  # functions.signature() 相当
+    return type(f"_Addon_{fn.__name__}", (functions.Functions,), {
+        f"_func_{fn.__name__}": _method,
+    })
+
+
+@lru_cache(maxsize=4096)
+def _compile(expression: str) -> jmespath.parser.ParsedResult:
+    """JMESPath 式をコンパイルする（結果はキャッシュされる）。"""
+    return jmespath.compile(expression)
+
+
+@lru_cache(maxsize=1024)
+def _make_options(*addon_classes: type) -> jmespath.Options:
+    """アドオン関数クラスを DefaultFunctions と合成して Options を生成する（結果はキャッシュされる）。
+
+    ``DefaultFunctions`` は常に末尾に含まれるため、アドオンの有無にかかわらず
+    デフォルト関数（format_date, upper, lower, strip, replace, split, match, coalesce, to_json_string）が利用できる。
+    複数アドオンは多重継承で合成されるため、同じ組み合わせは常に同一インスタンスを再利用する。
+
+    Args:
+        *addon_classes: ``jmespath.functions.Functions`` のサブクラス群
+    """
+    combined = type("_CombinedFunctions", (*addon_classes, DefaultFunctions), {})
+    return jmespath.Options(custom_functions=combined())
+
+
+def transform(expression: str, data: Any, *addon_funcs: Callable) -> Any:
+    """JMESPath 式を評価する。
+
+    任意のオブジェクトは ``_wrap()`` によって自動的に dict 風にラップされる。
+    ``DefaultFunctions`` は常に有効なので、アドオンなしでも
+    format_date / upper / lower / strip / replace / split / match / coalesce / to_json_string が使える。
+
+    Args:
+        expression: JMESPath 式文字列
+        data: 評価対象のデータ（dict, list, または任意のオブジェクト）
+        *addon_funcs: 追加のカスタム関数（型ヒント付き）。
+            引数の型ヒントから ``@functions.signature()`` 相当の宣言を自動生成する。
+
+    Returns:
+        JMESPath 評価結果
+
+    See:
+        https://jmespath.org/
+
+    Examples:
+        デフォルト関数なしで format_date や upper が利用できる::
+
+            result = transform("upper(name)", {"name": "alice"})
+            result = transform("{d: format_date(date_str, '%Y%m')}", {"date_str": "2025-03-01"})
+
+        オブジェクトを自動ラップ（明示的な AsDict 不要）::
+
+            result = transform("{message: err.message}", {"err": some_exception})
+
+        型ヒント付き関数を渡す::
+
+            def my_func(s: str) -> str:
+                return s[::-1]  # 逆字
+
+            result = transform("my_func(name)", data, my_func)
+
+        複数の関数を渡す::
+
+            result = transform("...", data, fn_a, fn_b)
+    """
+    addons = tuple(_func_to_addon_class(fn) for fn in addon_funcs)
+    result = _compile(expression).search(_wrap(data), options=_make_options(*addons))
+    logger.debug("transform: %s", result)
+    return result

jmesway-0.1.0/src/jmesway/roadmap.py

@@ -0,0 +1,299 @@
+"""``.roadmap.md`` パーサー兼 Dynamic Runner（Phase 1）。
+
+``docs/dev/DESIGN.md`` で定義された `.roadmap.md` フォーマットを読み込み、
+``RoadmapDocument`` に構造化する。パイプラインの実行（``pipeline().transform()``）と
+ドキュメントに書かれた IN/OUT の自己検証（``verify_all()``）を提供する。
+
+Markdown 自体は「見出し（レベル不問）＋フェンス付きコードブロックの出現順」という
+限定的な構造しか使わないため、汎用 Markdown パーサーには依存せず、行走査の専用
+パーサーを自作している。見出しの階層構造（セクション分けの深さ）は利用者に委ねられて
+おり、`@jmesway` マーカーが付いている見出しだけが Case として扱われる。マーカーの
+無い見出しは、配下に何が書かれていても（草稿や過去の例を含め）完全に無視される。
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import json5
+
+from .jmespath_transform import transform
+
+_HEADING_RE = re.compile(r"^#{1,6}\s+(.+?)(?:\s+(@jmesway)(?:\s+#(\w+))?)?\s*$")
+_FENCE_START_RE = re.compile(r"^```(\w+)\s*$")
+_FENCE_END_RE = re.compile(r"^```\s*$")
+_REF_LINK_RE = re.compile(r"^\[([^\]]+)\]\(#([^)]+)\)\s*$")
+
+# _scan_elements() が返す1要素: (種別, 値, 行番号(1-based))
+# 種別は "json5"（値はパース済みデータ）/ "jmespath"（値は式文字列）/ "ref"（値は参照先パイプライン名）
+_Element = tuple[str, Any, int]
+
+
+@dataclass
+class Pipeline:
+    """タグ付き Case から生成される、``|`` 連結済みの JMESPath 式。"""
+
+    name: str
+    expression: str
+
+    def transform(self, data: Any) -> Any:
+        return transform(self.expression, data)
+
+
+@dataclass
+class Step:
+    """Case 内の1段階（JMESPath 式と、それを適用した直後に期待される json5 値）。"""
+
+    expression: str
+    expected: Any
+
+
+class CaseVerificationError(AssertionError):
+    """``Case.verify()`` の失敗。どの Case / どの JMESPath 式で失敗したかを属性として保持する。"""
+
+    def __init__(self, case: Case, step_index: int, expression: str, expected: Any, actual: Any) -> None:
+        self.case = case
+        self.step_index = step_index
+        self.expression = expression
+        self.expected = expected
+        self.actual = actual
+        super().__init__(
+            f"{case.title} (line {case.line}): step {step_index} mismatch\n"
+            f"  expression: {expression}\n"
+            f"  expected: {expected!r}\n"
+            f"  actual:   {actual!r}"
+        )
+
+
+@dataclass
+class Case:
+    """``###`` 見出し1つ分（IN → Step の交互列）。"""
+
+    title: str
+    pipeline_name: str | None
+    references: str | None
+    input: Any
+    steps: list[Step]
+    line: int
+
+    def verify(self) -> None:
+        """IN から各 Step を順に適用し、期待値と一致するか検証する。
+
+        Raises:
+            CaseVerificationError: いずれかの段階で実際の結果が期待値と一致しない場合。
+        """
+        current = self.input
+        for i, step in enumerate(self.steps, start=1):
+            actual = transform(step.expression, current)
+            if actual != step.expected:
+                raise CaseVerificationError(self, i, step.expression, step.expected, actual)
+            current = actual
+
+
+@dataclass
+class RoadmapDocument:
+    """1つの ``.roadmap.md`` ファイルをパースした結果。"""
+
+    path: Path
+    cases: list[Case] = field(default_factory=list)
+    pipelines: dict[str, Pipeline] = field(default_factory=dict)
+
+    @classmethod
+    def load(cls, path: str | Path) -> RoadmapDocument:
+        path = Path(path)
+        return _parse(path, path.read_text(encoding="utf-8"))
+
+    def pipeline(self, name: str) -> Pipeline:
+        try:
+            return self.pipelines[name]
+        except KeyError:
+            raise KeyError(f"pipeline '{name}' is not defined in {self.path}") from None
+
+    def pipeline_cases(self, name: str) -> list[Case]:
+        """指定パイプラインを定義または参照している Case を出現順に返す。
+
+        build 済みの `.py` 関数を、roadmap.md の Case データでパラメタライズしてテストする
+        （利用者が自分のテストコードから呼ぶ）ためのヘルパー。
+        """
+        return [c for c in self.cases if c.pipeline_name == name or c.references == name]
+
+    def verify_all(self) -> None:
+        for case in self.cases:
+            case.verify()
+
+
+def _scan_elements(lines: list[str], start: int, end: int) -> list[_Element]:
+    """[start, end) の行範囲から、フェンス付きコードブロックとパイプライン参照リンクを出現順に抽出する。"""
+    elements: list[_Element] = []
+    i = start
+    while i < end:
+        line = lines[i]
+        fence_match = _FENCE_START_RE.match(line)
+        if fence_match:
+            lang = fence_match.group(1)
+            body_start = i + 1
+            j = body_start
+            while j < end and not _FENCE_END_RE.match(lines[j]):
+                j += 1
+            body = "\n".join(lines[body_start:j])
+            if lang == "json5":
+                elements.append(("json5", json5.loads(body), i + 1))
+            elif lang == "jmespath":
+                elements.append(("jmespath", body.strip(), i + 1))
+            i = j + 1
+            continue
+        ref_match = _REF_LINK_RE.match(line.strip())
+        if ref_match:
+            elements.append(("ref", ref_match.group(2), i + 1))
+        i += 1
+    return elements
+
+
+def _build_case(
+    path: Path,
+    title: str,
+    elements: list[_Element],
+    pipelines: dict[str, Pipeline],
+    line: int,
+) -> Case:
+    if not elements or elements[0][0] != "json5":
+        raise ValueError(f"{path}:{line}: case '{title}' must start with a json5 block (IN)")
+    if elements[-1][0] != "json5":
+        raise ValueError(f"{path}:{line}: case '{title}' must end with a json5 block (OUT)")
+
+    input_value = elements[0][1]
+    steps: list[Step] = []
+    references: str | None = None
+    i = 1
+    while i < len(elements):
+        if elements[i][0] == "json5":
+            raise ValueError(
+                f"{path}:{elements[i][2]}: case '{title}' has two consecutive json5 blocks; "
+                "expected a jmespath block or pipeline reference in between"
+            )
+        # 次の json5 が現れるまでの連続する jmespath/ref を `|` で連結し、1つの Step にまとめる。
+        # 中間の期待値を都度書かなくても、複数パイプラインの合成（mix）を1つの Step として書ける。
+        expr_parts: list[str] = []
+        j = i
+        while j < len(elements) and elements[j][0] != "json5":
+            kind, value, elem_line = elements[j]
+            if kind == "jmespath":
+                expr_parts.append(value)
+            else:  # "ref"
+                if value not in pipelines:
+                    raise ValueError(f"{path}:{elem_line}: unknown pipeline reference '#{value}'")
+                expr_parts.append(pipelines[value].expression)
+                if references is None:
+                    references = value
+            j += 1
+
+        if j >= len(elements):
+            kind_label = "jmespath expression" if elements[j - 1][0] == "jmespath" else "pipeline reference"
+            raise ValueError(f"{path}:{elements[j - 1][2]}: case '{title}' expects a json5 block after {kind_label}")
+        expected = elements[j][1]
+        steps.append(Step(expression=" | ".join(expr_parts), expected=expected))
+        i = j + 1
+
+    return Case(
+        title=title,
+        pipeline_name=None,
+        references=references,
+        input=input_value,
+        steps=steps,
+        line=line,
+    )
+
+
+
+def _find_headings(lines: list[str]) -> list[tuple[int, str, bool, str | None]]:
+    """フェンス外の見出し行を (0-based行番号, タイトル, @jmeswayマーカーの有無, タグ) のリストとして返す。
+
+    見出しレベル（`#`の個数）は区別しない。`@jmesway` が付いた見出しだけが Case 候補となり、
+    それ以外（タグやコードブロックがあっても）は完全に無視される。
+    """
+    headings: list[tuple[int, str, bool, str | None]] = []
+    in_fence = False
+    for idx, line in enumerate(lines):
+        if in_fence:
+            if _FENCE_END_RE.match(line):
+                in_fence = False
+            continue
+        if _FENCE_START_RE.match(line):
+            in_fence = True
+            continue
+        heading_match = _HEADING_RE.match(line)
+        if heading_match:
+            marker = heading_match.group(2) is not None
+            headings.append((idx, heading_match.group(1), marker, heading_match.group(3)))
+    return headings
+
+
+def _parse(path: Path, text: str) -> RoadmapDocument:
+    lines = text.splitlines()
+    n = len(lines)
+    headings = _find_headings(lines)
+
+    # `@jmesway` が付いた見出しだけを Case 候補として集める。マーカーの無い見出しは
+    # 目次・前書き・草稿・過去の例など、自由な地の文として完全に無視する。
+    raw_sections: list[tuple[str | None, str, int, list[_Element]]] = []
+    seen_tags: set[str] = set()
+    for i, (idx, title, marker, tag) in enumerate(headings):
+        if not marker:
+            continue
+        content_start = idx + 1
+        content_end = headings[i + 1][0] if i + 1 < len(headings) else n
+        elements = _scan_elements(lines, content_start, content_end)
+        heading_line = idx + 1
+        if tag:
+            if tag in seen_tags:
+                raise ValueError(f"{path}:{heading_line}: duplicate pipeline tag '#{tag}' (case '{title}')")
+            seen_tags.add(tag)
+        raw_sections.append((tag, title, heading_line, elements))
+
+    tagged_sections = {
+        tag: (elements, heading_line, title) for tag, title, heading_line, elements in raw_sections if tag
+    }
+
+    # パイプラインは、ファイル内のどこに定義されていても（前方参照でも）解決できるよう、
+    # Case を組み立てる前に一括で解決しておく。
+    pipelines: dict[str, Pipeline] = {}
+    resolving: set[str] = set()
+
+    def resolve_pipeline(name: str) -> Pipeline:
+        if name in pipelines:
+            return pipelines[name]
+        if name not in tagged_sections:
+            raise ValueError(f"{path}: unknown pipeline reference '#{name}'")
+        if name in resolving:
+            raise ValueError(f"{path}: circular pipeline reference involving '#{name}'")
+        resolving.add(name)
+        elements, heading_line, title = tagged_sections[name]
+        parts = [
+            resolve_pipeline(value).expression if kind == "ref" else value
+            for kind, value, _line in elements
+            if kind in ("jmespath", "ref")
+        ]
+        resolving.discard(name)
+        if not parts:
+            raise ValueError(
+                f"{path}:{heading_line}: pipeline '#{name}' (case '{title}') has no jmespath expression"
+            )
+        pipeline = Pipeline(name=name, expression=" | ".join(parts))
+        pipelines[name] = pipeline
+        return pipeline
+
+    for tag in tagged_sections:
+        resolve_pipeline(tag)
+
+    cases: list[Case] = []
+    for tag, title, heading_line, elements in raw_sections:
+        case = _build_case(path, title, elements, pipelines, heading_line)
+        if tag:
+            case.pipeline_name = tag
+        cases.append(case)
+
+    return RoadmapDocument(path=path, cases=cases, pipelines=pipelines)
+

jmesway-0.1.0/src/jmesway/transpiler.py

@@ -0,0 +1,58 @@
+"""``.roadmap.md`` から事前コンパイル済み `.py` を生成するトランスパイラ（Phase 3）。
+
+生成された関数は ``jmesway.jmespath_transform.transform()`` を実行基盤として使うため、
+``upper`` / ``match`` などの独自拡張関数もそのまま利用できる。
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .roadmap import Case, RoadmapDocument
+
+_HEADER_TEMPLATE = '''"""generated by `jmesway build` from {source}. DO NOT EDIT."""
+
+from typing import Any
+
+from jmesway.jmespath_transform import transform
+'''
+
+
+def output_path_for(source_path: Path) -> Path:
+    """``<name>.roadmap.md`` に対応する生成先 ``<name>.py`` のパスを返す。"""
+    name = source_path.name
+    suffix = ".roadmap.md"
+    stem = name[: -len(suffix)] if name.endswith(suffix) else source_path.stem
+    return source_path.with_name(f"{stem}.py")
+
+
+def _render_function(name: str, expression: str, case: Case | None) -> str:
+    const_name = name.upper()
+    if case is not None:
+        sample = (
+            f"\n\n    IN:  {json.dumps(case.input, ensure_ascii=False)}"
+            f"\n    OUT: {json.dumps(case.steps[-1].expected, ensure_ascii=False)}"
+        )
+        summary = case.title
+    else:
+        summary = name
+        sample = ""
+    return (
+        f"{const_name} = {expression!r}\n\n\n"
+        f"def {name}(data: Any) -> Any:\n"
+        f'    """{summary}{sample}\n    """\n'
+        f"    return transform({const_name}, data)\n"
+    )
+
+
+def generate_source(doc: RoadmapDocument, source_path: Path) -> str:
+    """``doc`` の全パイプラインから、事前コンパイル済みの `.py` ソースコードを生成する。"""
+    case_by_pipeline = {case.pipeline_name: case for case in doc.cases if case.pipeline_name}
+
+    parts = [_HEADER_TEMPLATE.format(source=source_path.as_posix())]
+    for name, pipeline in doc.pipelines.items():
+        parts.append(_render_function(name, pipeline.expression, case_by_pipeline.get(name)))
+
+    return "\n".join(parts).rstrip() + "\n"
+