hython-lang 2.0.0__py3-none-any.whl

hython/hir.py

@@ -0,0 +1,93 @@
+"""Hython Intermediate Representation and conservative optimizer."""
+from __future__ import annotations
+from dataclasses import dataclass, field
+import operator
+
+@dataclass
+class HIRCode:
+    name: str
+    parameters: list[str]
+    constants: list[object] = field(default_factory=list)
+    instructions: list[list] = field(default_factory=list)
+    lines: list[int] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "parameters": self.parameters, "constants": self.constants, "instructions": self.instructions,"lines":self.lines}
+
+    @classmethod
+    def from_dict(cls,value:dict) -> "HIRCode":
+        return cls(value["name"],value["parameters"],value["constants"],value["instructions"],value.get("lines",[]))
+
+_BINARY = {"ADD":operator.add,"SUB":operator.sub,"MUL":operator.mul,"DIV":operator.truediv,
+           "FLOORDIV":operator.floordiv,"MOD":operator.mod,"POW":operator.pow,
+           "EQ":operator.eq,"NE":operator.ne,"LT":operator.lt,"LE":operator.le,
+           "GT":operator.gt,"GE":operator.ge,"IS":operator.is_}
+_UNARY = {"NEG":operator.neg,"POS":operator.pos,"NOT":operator.not_}
+
+def optimize_hir(code: HIRCode) -> HIRCode:
+    """Fold safe constants without changing instruction offsets."""
+    ins = code.instructions
+    for index in range(len(ins) - 2):
+        first, second, third = ins[index:index + 3]
+        if first[0] == second[0] == "CONST" and third[0] in _BINARY:
+            try:
+                value = _BINARY[third[0]](code.constants[first[1]], code.constants[second[1]])
+            except Exception:
+                continue
+            if isinstance(value, (type(None), bool, int, float, str)):
+                code.constants.append(value)
+                ins[index:index + 3] = [["CONST", len(code.constants)-1], ["NOP"], ["NOP"]]
+    for index in range(len(ins) - 1):
+        first, second = ins[index:index + 2]
+        if first[0] == "CONST" and second[0] in _UNARY:
+            try: value = _UNARY[second[0]](code.constants[first[1]])
+            except Exception: continue
+            code.constants.append(value)
+            ins[index:index + 2] = [["CONST", len(code.constants)-1], ["NOP"]]
+    for instruction in ins:
+        if instruction[0] in ("MAKE_FUNCTION","MAKE_CLASS"):
+            nested = instruction[1]["code"]
+            child = HIRCode.from_dict(nested)
+            optimized=optimize_hir(child).to_dict()
+            instruction[1]["code"]=optimized
+        elif instruction[0]=="TRY":
+            payload=instruction[1]
+            for key in ("body","else","finally"):
+                nested=payload.get(key)
+                if nested:
+                    payload[key]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+            for handler in payload["handlers"]:
+                nested=handler["code"]
+                handler["code"]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+        elif instruction[0]=="COMPREHENSION":
+            payload=instruction[1]
+            for key in ("element","key","value"):
+                nested=payload.get(key)
+                if nested: payload[key]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+            for clause in payload["clauses"]:
+                nested=clause["iter"]
+                clause["iter"]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+                clause["filters"]=[optimize_hir(HIRCode.from_dict(n)).to_dict() for n in clause["filters"]]
+        elif instruction[0]=="WITH":
+            payload=instruction[1]; nested=payload["body"]
+            payload["body"]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+            for manager in payload["managers"]:
+                nested=manager["code"]
+                manager["code"]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+        elif instruction[0] in ("ASYNC_FOR","ASYNC_WITH"):
+            payload=instruction[1]
+            for key in ("iter","body","else"):
+                nested=payload.get(key)
+                if nested: payload[key]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+            for manager in payload.get("managers",[]):
+                nested=manager["code"]; manager["code"]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+        elif instruction[0]=="ANNOTATE_LAZY":
+            nested=instruction[1]["code"]; instruction[1]["code"]=optimize_hir(HIRCode.from_dict(nested)).to_dict()
+    return code
+
+def format_hir(code: HIRCode) -> str:
+    lines = [f"HIR {code.name}({', '.join(code.parameters)})"]
+    for index, instruction in enumerate(code.instructions):
+        argument = " ".join(map(str, instruction[1:]))
+        lines.append(f"{index:04d}  {instruction[0]:14} {argument}")
+    return "\n".join(lines)

hython/importer.py

@@ -0,0 +1,76 @@
+"""Import hook for loading ``.hy`` source modules and packages."""
+
+from __future__ import annotations
+
+import importlib.abc
+import importlib.machinery
+import importlib.util
+import sys
+from pathlib import Path
+
+from .translator import compile_hython
+
+
+class HythonLoader(importlib.abc.SourceLoader):
+    """Load a Hython source file as a normal Python module."""
+
+    def __init__(self, fullname: str, path: Path) -> None:
+        self.fullname = fullname
+        self.path = path
+
+    def get_filename(self, fullname: str) -> str:
+        return str(self.path)
+
+    def get_data(self, path: str) -> bytes:
+        return Path(path).read_bytes()
+
+    def get_code(self, fullname: str):
+        source = self.path.read_text(encoding="utf-8-sig")
+        return compile_hython(source, str(self.path))
+
+    def set_data(self, path: str, data: bytes, *, _mode: int = 0o666) -> None:
+        # Do not create misleading CPython .pyc cache files for Hython sources.
+        return None
+
+
+class HythonFinder(importlib.abc.MetaPathFinder):
+    """Find ``name.hy`` and ``name/__init__.hy`` on the import path."""
+
+    marker = "hython-finder-v1"
+
+    def find_spec(self, fullname: str, path=None, target=None):
+        name = fullname.rpartition(".")[2]
+        search_paths = sys.path if path is None else path
+        for entry in search_paths:
+            base = Path(entry or ".")
+            package_file = base / name / "__init__.hy"
+            if package_file.is_file():
+                loader = HythonLoader(fullname, package_file)
+                return importlib.util.spec_from_file_location(
+                    fullname,
+                    package_file,
+                    loader=loader,
+                    submodule_search_locations=[str(package_file.parent)],
+                )
+            module_file = base / f"{name}.hy"
+            if module_file.is_file():
+                return importlib.util.spec_from_file_location(
+                    fullname, module_file, loader=HythonLoader(fullname, module_file)
+                )
+        return None
+
+
+def install_importer() -> HythonFinder:
+    """Install the finder once, ahead of Python's normal path finder."""
+    for finder in sys.meta_path:
+        if isinstance(finder, HythonFinder):
+            return finder
+    finder = HythonFinder()
+    sys.meta_path.insert(0, finder)
+    return finder
+
+
+def uninstall_importer() -> None:
+    """Remove all installed Hython finders (mainly useful for tests)."""
+    sys.meta_path[:] = [finder for finder in sys.meta_path if not isinstance(finder, HythonFinder)]
+

hython/package_manager.py

@@ -0,0 +1,343 @@
+"""Package installation and safe, static public-API dictionary generation."""
+
+from __future__ import annotations
+
+import ast
+import importlib.machinery
+import importlib.metadata
+import json
+import re
+import subprocess
+import sys
+import sysconfig
+import tempfile
+from pathlib import Path
+
+from .phonetics import pronounce_identifier
+from .environment import is_frozen, package_store
+
+
+_DEEP_SCAN_SCRIPT = r"""
+import importlib, inspect, json, sys
+if sys.argv[2]:
+    sys.path.insert(0, sys.argv[2])
+module = importlib.import_module(sys.argv[1])
+names = set()
+def visit(obj, depth=0):
+    try:
+        members = inspect.getmembers_static(obj)
+    except Exception:
+        return
+    for name, value in members:
+        if not name.startswith("_"):
+            names.add(name)
+            if depth == 0 and inspect.isclass(value):
+                visit(value, 1)
+visit(module)
+print("__HYTHON_API__" + json.dumps(sorted(names), ensure_ascii=False))
+"""
+
+_DICTIONARY_CACHE_KEY: tuple[tuple[str, int, int], ...] | None = None
+_DICTIONARY_CACHE: dict[str, str] = {}
+
+
+def infer_module_name(spec: str) -> str:
+    """Infer an import name from a PEP 508-style distribution specifier."""
+    match=re.match(r"\s*([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)",spec)
+    if not match or spec[match.end():match.end()+1] not in ("","[","<",">","=","!","~","@"," ","\t"):
+        raise ValueError("패키지 지정자에서 모듈명을 추론할 수 없습니다. --module을 지정하세요.")
+    return match.group(1).replace("-","_")
+
+
+def modules_for_distribution(spec: str, fallback: str | None = None) -> list[str]:
+    """Return every top-level import supplied by a distribution."""
+    distribution = infer_module_name(spec)
+    normalized = re.sub(r"[-_.]+", "-", distribution).lower()
+    modules = {
+        module
+        for module, distributions in importlib.metadata.packages_distributions().items()
+        if any(re.sub(r"[-_.]+", "-", item).lower() == normalized for item in distributions)
+        and module.isidentifier()
+    }
+    if fallback:
+        modules.add(fallback)
+    elif not modules:
+        modules.add(distribution)
+    return sorted(modules)
+
+
+def dictionary_dir() -> Path:
+    root = Path(__import__("os").environ.get("HYTHON_HOME", Path.home() / ".hython")) / "dictionaries"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def install(package: str, *, upgrade: bool = False) -> None:
+    """Install through the current interpreter; subprocess avoids pip internals."""
+    if is_frozen():
+        from .runtime_manager import find_manager
+        command=[find_manager(),"exec","-V:default","-m","pip","install","--target",str(package_store())]
+    else:
+        command = [sys.executable, "-m", "pip", "install"]
+    if upgrade:
+        command.append("--upgrade")
+    command.append(package)
+    subprocess.run(command, check=True)
+
+
+def uninstall(package: str) -> None:
+    """Remove a distribution through pip."""
+    if is_frozen():
+        from .runtime_manager import find_manager
+        env=__import__("os").environ.copy()
+        env["PYTHONPATH"]=str(package_store())+__import__("os").pathsep+env.get("PYTHONPATH","")
+        command=[find_manager(),"exec","-V:default","-m","pip","uninstall","-y",package]
+        subprocess.run(command,check=True,env=env)
+    else:
+        subprocess.run([sys.executable,"-m","pip","uninstall","-y",package],check=True)
+
+
+def _public_names(path: Path) -> set[str]:
+    names: set[str] = set()
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8-sig"), filename=str(path))
+    except (OSError, UnicodeError, SyntaxError):
+        return names
+    explicit_all: set[str] = set()
+    def collect_node(node: ast.AST) -> None:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            if not node.name.startswith("_"):
+                names.add(node.name)
+            # Public methods and nested public API classes are part of the
+            # spelling surface too (for example tkinter's title/mainloop).
+            if isinstance(node, ast.ClassDef):
+                for child in node.body:
+                    collect_node(child)
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                exposed = alias.asname or alias.name.split(".")[0]
+                if exposed != "*" and not exposed.startswith("_"):
+                    names.add(exposed)
+        elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            for target in targets:
+                if isinstance(target, ast.Name) and not target.id.startswith("_"):
+                    names.add(target.id)
+            if isinstance(node, ast.Assign) and any(
+                isinstance(target, ast.Name) and target.id == "__all__" for target in node.targets
+            ) and isinstance(node.value, (ast.List, ast.Tuple)):
+                explicit_all.update(
+                    item.value for item in node.value.elts
+                    if isinstance(item, ast.Constant) and isinstance(item.value, str)
+                )
+    for node in tree.body:
+        collect_node(node)
+    return explicit_all or names
+
+
+def _deep_public_names(module: str, timeout: int = 30) -> set[str]:
+    """Inspect extension/dynamic exports in an isolated child interpreter."""
+    if is_frozen():
+        from .runtime_manager import find_manager
+        command = [
+            find_manager(), "exec", "-V:default", "-c", _DEEP_SCAN_SCRIPT,
+            module, str(package_store()),
+        ]
+    else:
+        command = [sys.executable, "-I", "-c", _DEEP_SCAN_SCRIPT, module, ""]
+    result = subprocess.run(
+        command, text=True, capture_output=True, errors="replace", timeout=timeout
+    )
+    if result.returncode:
+        detail = (result.stderr or result.stdout).strip().splitlines()
+        raise RuntimeError(
+            "패키지 심층 API 분석 실패: " + (detail[-1] if detail else module)
+        )
+    marker = next(
+        (line.removeprefix("__HYTHON_API__") for line in result.stdout.splitlines()
+         if line.startswith("__HYTHON_API__")),
+        None,
+    )
+    if marker is None:
+        raise RuntimeError("패키지 심층 API 분석 결과를 읽을 수 없습니다.")
+    payload = json.loads(marker)
+    return {name for name in payload if isinstance(name, str)}
+
+
+def _unique_spellings(
+    names: set[str], reserved: dict[str, str] | None = None
+) -> dict[str, str]:
+    """Give every public API a deterministic, collision-free Hangul spelling."""
+    result: dict[str, str] = {}
+    occupied: dict[str, str] = dict(reserved or {})
+    for name in sorted(names, key=lambda item: (pronounce_identifier(item), item)):
+        base = pronounce_identifier(name)
+        spoken = base
+        suffix = 2
+        while spoken in occupied and occupied[spoken] != name:
+            spoken = f"{base}{suffix}"
+            suffix += 1
+        result[name] = spoken
+        occupied[spoken] = name
+    return result
+
+
+def scan(module: str, *, deep: bool = False) -> Path:
+    """Statically scan a module/package without importing or executing it."""
+    spec = _find_spec_static(module)
+    if spec is None:
+        raise ModuleNotFoundError(f"패키지를 찾을 수 없습니다: {module}")
+    files: list[Path] = []
+    if spec.submodule_search_locations:
+        for location in spec.submodule_search_locations:
+            files.extend(Path(location).rglob("*.py"))
+    elif spec.origin and spec.origin.endswith(".py"):
+        files.append(Path(spec.origin))
+    # The module spelling itself must be translatable in an import statement.
+    names: set[str] = {part for part in module.split(".") if not part.startswith("_")}
+    for file in files:
+        names.update(_public_names(file))
+    if deep:
+        names.update(_deep_public_names(module))
+    from .vocabulary import HYTHON_TO_PYTHON
+    python_to_hython = _unique_spellings(
+        names, load_dictionaries() | HYTHON_TO_PYTHON
+    )
+    payload = {
+        "format": 1,
+        "module": module,
+        "scan_mode": "deep" if deep else "static",
+        "distribution_version": _version_for(module),
+        "python_to_hython": python_to_hython,
+    }
+    output = dictionary_dir() / f"{module.replace('.', '__')}.json"
+    _atomic_json(output, payload)
+    return output
+
+
+def scan_standard_library() -> Path:
+    """Build one collision-free dictionary for the active Python stdlib."""
+    root = Path(sysconfig.get_paths()["stdlib"])
+    names = {
+        name for name in getattr(sys, "stdlib_module_names", ())
+        if isinstance(name, str) and not name.startswith("_")
+    }
+    for file in root.rglob("*.py"):
+        lowered = {part.lower() for part in file.parts}
+        if "site-packages" in lowered or "dist-packages" in lowered:
+            continue
+        names.update(_public_names(file))
+    from .vocabulary import HYTHON_TO_PYTHON
+    spellings = _unique_spellings(names, load_dictionaries() | HYTHON_TO_PYTHON)
+    output = dictionary_dir() / "_stdlib.json"
+    _atomic_json(output, {
+        "format": 1,
+        "module": "__stdlib__",
+        "scan_mode": "stdlib",
+        "python_version": sys.version.split()[0],
+        "python_to_hython": spellings,
+    })
+    return output
+
+
+def _atomic_json(output: Path, payload: dict) -> None:
+    handle, temporary = tempfile.mkstemp(prefix=output.name + ".", suffix=".tmp", dir=output.parent)
+    try:
+        with __import__("os").fdopen(handle, "w", encoding="utf-8", newline="\n") as stream:
+            json.dump(payload, stream, ensure_ascii=False, indent=2)
+            stream.write("\n")
+            stream.flush()
+            __import__("os").fsync(stream.fileno())
+        Path(temporary).replace(output)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise
+
+
+def remove_dictionary(module: str) -> bool:
+    path = dictionary_dir() / f"{module.replace('.', '__')}.json"
+    existed = path.exists()
+    path.unlink(missing_ok=True)
+    return existed
+
+
+def refresh_dictionaries() -> tuple[list[Path], list[Path]]:
+    """Rescan installed modules and prune dictionaries whose packages disappeared."""
+    refreshed: list[Path] = []
+    removed: list[Path] = []
+    for path in sorted(dictionary_dir().glob("*.json")):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            module = payload["module"]
+            if not isinstance(module, str):
+                continue
+        except (OSError, UnicodeError, json.JSONDecodeError, KeyError):
+            continue
+        if module == "__stdlib__":
+            refreshed.append(scan_standard_library())
+        elif _find_spec_static(module) is None:
+            path.unlink(missing_ok=True)
+            removed.append(path)
+        else:
+            refreshed.append(scan(module, deep=payload.get("scan_mode") == "deep"))
+    return refreshed, removed
+
+
+def _find_spec_static(module: str):
+    """Resolve dotted modules without importing their parent packages."""
+    if not module or any(not part for part in module.split(".")):
+        return None
+    search_path = None
+    fullname = ""
+    spec = None
+    for part in module.split("."):
+        fullname = f"{fullname}.{part}" if fullname else part
+        spec = importlib.machinery.PathFinder.find_spec(fullname, search_path)
+        if spec is None:
+            return None
+        search_path = spec.submodule_search_locations
+    return spec
+
+
+def _version_for(module: str) -> str | None:
+    packages = importlib.metadata.packages_distributions()
+    distributions = packages.get(module.split(".")[0], [])
+    if not distributions:
+        return None
+    try:
+        return importlib.metadata.version(distributions[0])
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def load_dictionaries() -> dict[str, str]:
+    """Load valid user dictionaries as Hython-to-Python mappings."""
+    global _DICTIONARY_CACHE_KEY, _DICTIONARY_CACHE
+    paths = sorted(dictionary_dir().glob("*.json"))
+    key = tuple(
+        (str(path), stat.st_mtime_ns, stat.st_size)
+        for path in paths
+        if (stat := path.stat())
+    )
+    if key == _DICTIONARY_CACHE_KEY:
+        return dict(_DICTIONARY_CACHE)
+    result: dict[str, str] = {}
+    for path in paths:
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8"))
+            entries = payload["python_to_hython"]
+            if not isinstance(entries, dict):
+                continue
+            for python_name, spoken in entries.items():
+                if isinstance(python_name, str) and isinstance(spoken, str):
+                    result.setdefault(spoken, python_name)
+        except (OSError, UnicodeError, json.JSONDecodeError, KeyError):
+            continue
+    _DICTIONARY_CACHE_KEY = key
+    _DICTIONARY_CACHE = dict(result)
+    return result
+
+
+def load_python_dictionaries() -> dict[str, str]:
+    """Load valid user dictionaries as Python-to-Hython mappings."""
+    return {python: spoken for spoken, python in load_dictionaries().items()}

hython/phonetics.py

@@ -0,0 +1,49 @@
+"""Deterministic English-identifier to Hangul phonetic approximation."""
+
+from __future__ import annotations
+
+import re
+
+# Longest fragments are applied first. This is deliberately deterministic: users
+# may edit generated dictionaries when a package's preferred pronunciation differs.
+_SOUNDS = {
+    "tion": "션", "sion": "전", "ough": "오", "ight": "아이트",
+    "ph": "프", "sh": "시", "ch": "치", "th": "스", "wh": "우",
+    "ck": "크", "qu": "쿠", "ng": "응", "ee": "이", "oo": "우",
+    "ai": "에이", "ay": "에이", "ea": "이", "ou": "아우", "ow": "오우",
+    "a": "아", "b": "브", "c": "크", "d": "드", "e": "에",
+    "f": "프", "g": "그", "h": "흐", "i": "이", "j": "제이",
+    "k": "크", "l": "르", "m": "므", "n": "느", "o": "오",
+    "p": "프", "q": "큐", "r": "르", "s": "스", "t": "트",
+    "u": "유", "v": "브", "w": "우", "x": "엑스", "y": "이",
+    "z": "즈",
+}
+_PARTS = sorted(_SOUNDS, key=len, reverse=True)
+
+
+def pronounce_word(word: str) -> str:
+    """Return a stable Hangul approximation for one ASCII word."""
+    result: list[str] = []
+    lowered = word.lower()
+    index = 0
+    while index < len(lowered):
+        if lowered[index].isdigit():
+            result.append(lowered[index])
+            index += 1
+            continue
+        for part in _PARTS:
+            if lowered.startswith(part, index):
+                result.append(_SOUNDS[part])
+                index += len(part)
+                break
+        else:
+            result.append(lowered[index])
+            index += 1
+    return "".join(result)
+
+
+def pronounce_identifier(name: str) -> str:
+    """Pronounce snake_case and CamelCase identifiers while preserving underscores."""
+    expanded = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", "_", name)
+    expanded = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", expanded)
+    return "_".join(pronounce_word(part) for part in expanded.split("_"))

hython/runtime.py

@@ -0,0 +1,110 @@
+"""Python runtime discovery and Hython syntax compatibility profiles."""
+
+from __future__ import annotations
+
+import json
+import keyword
+import platform
+import sys
+import sysconfig
+import tempfile
+from pathlib import Path
+
+from .phonetics import pronounce_identifier
+from .translator import to_python
+from .vocabulary import KEYWORDS
+from .environment import display_executable
+
+
+def profile_dir() -> Path:
+    path = Path(__import__("os").environ.get("HYTHON_HOME", Path.home() / ".hython")) / "runtimes"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def inspect_runtime() -> dict:
+    """Inspect the active interpreter instead of assuming a Python grammar version."""
+    hard = sorted(keyword.kwlist)
+    soft = sorted(getattr(keyword, "softkwlist", []))
+    known = set(KEYWORDS)
+    # Pattern wildcard `_` is intentionally identical in Hython.
+    discovered = [name for name in hard + soft if name not in known and name != "_"]
+    return {
+        "format": 1,
+        "implementation": platform.python_implementation(),
+        "version": platform.python_version(),
+        "version_info": list(sys.version_info[:3]),
+        "executable": str(display_executable()),
+        "platform": sysconfig.get_platform(),
+        "hard_keywords": hard,
+        "soft_keywords": soft,
+        "new_keywords": discovered,
+        "generated_spellings": {
+            name: pronounce_identifier(name) for name in discovered
+        },
+    }
+
+
+def sync_runtime() -> Path:
+    """Persist a reproducible profile for the active Python runtime."""
+    profile = inspect_runtime()
+    output = profile_dir() / f"python-{profile['version']}.json"
+    _atomic_json(output, profile)
+    # Keep the entire standard-library API pronunciation layer matched to the
+    # selected Python version. This state lives outside the installed core.
+    from .package_manager import scan_standard_library
+    scan_standard_library()
+    return output
+
+
+def _atomic_json(output: Path, payload: dict) -> None:
+    """Replace generated state without exposing a half-written profile."""
+    output.parent.mkdir(parents=True, exist_ok=True)
+    handle, temporary = tempfile.mkstemp(prefix=output.name + ".", suffix=".tmp", dir=output.parent)
+    try:
+        with __import__("os").fdopen(handle, "w", encoding="utf-8", newline="\n") as stream:
+            json.dump(payload, stream, ensure_ascii=False, indent=2)
+            stream.write("\n")
+            stream.flush()
+            __import__("os").fsync(stream.fileno())
+        Path(temporary).replace(output)
+    except BaseException:
+        Path(temporary).unlink(missing_ok=True)
+        raise
+
+
+def load_runtime_spellings() -> dict[str, str]:
+    """Return generated spellings for the active interpreter only."""
+    path = profile_dir() / f"python-{platform.python_version()}.json"
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        entries = payload.get("generated_spellings", {})
+        if payload.get("format") != 1 or not isinstance(entries, dict):
+            return {}
+        return {
+            spoken: python_name for python_name, spoken in entries.items()
+            if isinstance(python_name, str) and isinstance(spoken, str)
+        }
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return {}
+
+
+def check_file(path: Path) -> tuple[bool, str | None]:
+    """Compile a Hython file with the active interpreter without executing it."""
+    try:
+        source = path.read_text(encoding="utf-8-sig")
+        compile(to_python(source), str(path), "exec")
+    except (OSError, UnicodeError, SyntaxError) as exc:
+        return False, str(exc)
+    return True, None
+
+
+def check_tree(root: Path) -> list[tuple[Path, str]]:
+    """Return syntax failures for all Hython files under a path."""
+    paths = [root] if root.is_file() else sorted(root.rglob("*.hy"))
+    failures: list[tuple[Path, str]] = []
+    for path in paths:
+        valid, error = check_file(path)
+        if not valid:
+            failures.append((path, error or "알 수 없는 오류"))
+    return failures