pythsol 0.1.0__py3-none-any.whl

pythsol/client/port.py

@@ -0,0 +1,355 @@
+"""Turn an Anchor-legacy IDL into a PythSol program skeleton.
+
+The bodies are ``pass``. Account wrappers are inferred: a ``seeds`` constraint
+becomes ``Seeds[Init[T], "seed"]``, a mutable account on ``initialize`` /
+``init`` / ``make`` / ``create`` / ``open`` becomes ``Init[T]``, and other
+mutable accounts become ``Mut[T]``. The compiler still has to accept the
+result; fill the bodies in before the program can run.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["render_port"]
+
+_INIT_NAMES = {"initialize", "init", "make", "create", "open"}
+_SCALARS = {"u8", "u16", "u32", "u64", "u128", "i8", "i16", "i32", "i64", "i128"}
+_WRAPPERS = ("Seeds[", "HasOne[", "CloseTo[", "Address[", "Owner[")
+
+
+class PortError(Exception):
+    """The IDL is too incomplete to sketch a program."""
+
+
+def render_port(idl: dict[str, Any]) -> str:
+    """Return Python source for a skeleton program."""
+    program = str(idl.get("name") or "program")
+    types = _type_map(idl)
+    accounts = [item for item in idl.get("accounts") or [] if isinstance(item, dict)]
+    if not accounts:
+        raise PortError("IDL has no accounts to port")
+    imports: set[str] = {"account", "instruction"}
+    blocks: list[str] = []
+    for info in types.values():
+        body = info.get("type")
+        if isinstance(body, dict) and body.get("kind") == "enum":
+            imports.add("enum")
+            blocks.append(_enum_block(info))
+    for info in types.values():
+        if _is_user_struct(info):
+            imports.add("struct")
+            blocks.append(_struct_block(info, types, imports))
+    for account in accounts:
+        blocks.append(_account_block(account, types, imports))
+    errors = [item for item in idl.get("errors") or [] if isinstance(item, dict)]
+    if errors:
+        imports.update({"error", "ProgramError"})
+        blocks.append(_error_block(program, errors))
+    instructions = [item for item in idl.get("instructions") or [] if isinstance(item, dict)]
+    if not instructions:
+        raise PortError("IDL has no instructions to port")
+    for instr in instructions:
+        blocks.append(_instruction_block(instr, accounts, types, imports))
+    header = [
+        f'"""Ported from the `{program}` IDL.',
+        "",
+        "Each instruction body is a placeholder. Replace ``pass`` with the program.",
+        '"""',
+        "",
+        "from pythsol import (",
+    ]
+    for name in _import_lines(imports):
+        header.append(f"    {name},")
+    header.append(")")
+    header.append("")
+    return "\n".join([*header, "", *blocks]).rstrip() + "\n"
+
+
+def _import_lines(names: set[str]) -> list[str]:
+    order = [
+        "Account",
+        "Address",
+        "CloseTo",
+        "FixedArray",
+        "FixedString",
+        "HasOne",
+        "Init",
+        "Mut",
+        "Option",
+        "Owner",
+        "ProgramError",
+        "Pubkey",
+        "Seeds",
+        "Signer",
+        "account",
+        "enum",
+        "error",
+        "instruction",
+        "struct",
+        "u8",
+        "u16",
+        "u32",
+        "u64",
+        "u128",
+        "i8",
+        "i16",
+        "i32",
+        "i64",
+        "i128",
+    ]
+    return [name for name in order if name in names]
+
+
+def _type_map(idl: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    found: dict[str, dict[str, Any]] = {}
+    for item in idl.get("types") or []:
+        if isinstance(item, dict) and isinstance(item.get("name"), str):
+            found[item["name"]] = item
+    return found
+
+
+def _snake(name: str) -> str:
+    out: list[str] = []
+    for char in name:
+        if char.isupper() and out and out[-1] != "_":
+            out.append("_")
+        out.append(char.lower())
+    return "".join(out)
+
+
+def _pascal(name: str) -> str:
+    parts = name.replace("-", "_").split("_")
+    return "".join(part[:1].upper() + part[1:] for part in parts if part) or "Program"
+
+
+def _is_user_struct(info: dict[str, Any]) -> bool:
+    body = info.get("type")
+    if not isinstance(body, dict) or body.get("kind") != "struct":
+        return False
+    fields = body.get("fields")
+    if not isinstance(fields, list):
+        return False
+    if (
+        len(fields) == 2
+        and isinstance(fields[0], dict)
+        and isinstance(fields[1], dict)
+        and fields[0].get("name") == "tag"
+        and fields[1].get("name") == "value"
+    ):
+        return False
+    return not (
+        len(fields) == 2
+        and isinstance(fields[0], dict)
+        and isinstance(fields[1], dict)
+        and fields[0].get("name") == "len"
+        and fields[1].get("name") == "data"
+    )
+
+
+def _annotation(ty: Any, types: dict[str, dict[str, Any]], imports: set[str]) -> str:
+    if ty == "publicKey":
+        imports.add("Pubkey")
+        return "Pubkey"
+    if ty == "bool":
+        return "bool"
+    if isinstance(ty, str) and ty in _SCALARS:
+        imports.add(ty)
+        return ty
+    if isinstance(ty, dict) and isinstance(ty.get("array"), list) and len(ty["array"]) == 2:
+        inner, count = ty["array"]
+        imports.add("FixedArray")
+        return f"FixedArray[{_annotation(inner, types, imports)}, {count}]"
+    if isinstance(ty, dict) and isinstance(ty.get("option"), (str, dict)):
+        imports.add("Option")
+        return f"Option[{_annotation(ty['option'], types, imports)}]"
+    if isinstance(ty, dict) and isinstance(ty.get("defined"), str):
+        return _defined(ty["defined"], types, imports)
+    imports.add("u64")
+    return "u64"
+
+
+def _defined(name: str, types: dict[str, dict[str, Any]], imports: set[str]) -> str:
+    info = types.get(name)
+    body = info.get("type") if isinstance(info, dict) else None
+    if not isinstance(body, dict):
+        return name
+    if body.get("kind") == "enum":
+        return name
+    fields = body.get("fields")
+    if isinstance(fields, list) and len(fields) == 2:
+        first, second = fields[0], fields[1]
+        if (
+            isinstance(first, dict)
+            and isinstance(second, dict)
+            and first.get("name") == "tag"
+            and second.get("name") == "value"
+        ):
+            imports.add("Option")
+            return f"Option[{_annotation(second.get('type'), types, imports)}]"
+        if (
+            isinstance(first, dict)
+            and isinstance(second, dict)
+            and first.get("name") == "len"
+            and second.get("name") == "data"
+            and isinstance(second.get("type"), dict)
+            and isinstance(second["type"].get("array"), list)
+        ):
+            imports.add("FixedString")
+            return f"FixedString[{second['type']['array'][1]}]"
+    return name
+
+
+def _enum_block(info: dict[str, Any]) -> str:
+    name = str(info.get("name") or "Enum")
+    body = info.get("type") if isinstance(info.get("type"), dict) else {}
+    variants = body.get("variants") if isinstance(body, dict) else []
+    lines = ["@enum", f"class {name}:"]
+    if not isinstance(variants, list) or not variants:
+        lines.append("    pass")
+        return "\n".join(lines)
+    for index, variant in enumerate(variants):
+        label = "Variant"
+        if isinstance(variant, dict) and isinstance(variant.get("name"), str):
+            label = variant["name"]
+        lines.append(f"    {label} = {index}")
+    return "\n".join(lines)
+
+
+def _struct_block(info: dict[str, Any], types: dict[str, dict[str, Any]], imports: set[str]) -> str:
+    name = str(info.get("name") or "Struct")
+    body = info.get("type") if isinstance(info.get("type"), dict) else {}
+    fields = body.get("fields") if isinstance(body, dict) else []
+    lines = ["@struct", f"class {name}:"]
+    if not isinstance(fields, list) or not fields:
+        lines.append("    pass")
+        return "\n".join(lines)
+    for field in fields:
+        if not isinstance(field, dict):
+            continue
+        field_name = str(field.get("name") or "field")
+        lines.append(f"    {field_name}: {_annotation(field.get('type'), types, imports)}")
+    return "\n".join(lines)
+
+
+def _account_block(
+    account: dict[str, Any],
+    types: dict[str, dict[str, Any]],
+    imports: set[str],
+) -> str:
+    name = str(account.get("name") or "Account")
+    body = account.get("type") if isinstance(account.get("type"), dict) else {}
+    fields = body.get("fields") if isinstance(body, dict) else []
+    lines = ["@account", f"class {name}:"]
+    if not isinstance(fields, list) or not fields:
+        lines.append("    pass")
+        return "\n".join(lines)
+    for field in fields:
+        if not isinstance(field, dict):
+            continue
+        field_name = str(field.get("name") or "field")
+        lines.append(f"    {field_name}: {_annotation(field.get('type'), types, imports)}")
+    return "\n".join(lines)
+
+
+def _error_block(program: str, errors: list[dict[str, Any]]) -> str:
+    lines = [
+        "@error",
+        f"class {_pascal(program)}Error(ProgramError):",
+        '    """Ported error names. Codes on chain are 6000 + declaration index."""',
+    ]
+    for index, error in enumerate(errors):
+        label = str(error.get("name") or f"Error{index}")
+        lines.append(f"    {label} = {index}")
+    return "\n".join(lines)
+
+
+def _match_account(param: str, accounts: list[dict[str, Any]]) -> str | None:
+    for account in accounts:
+        name = str(account.get("name") or "")
+        if name == param or _snake(name) == param:
+            return name
+    return None
+
+
+def _constraint(account: dict[str, Any], kind: str, key: str) -> str | None:
+    raw = account.get("constraints")
+    if not isinstance(raw, list):
+        return None
+    for item in raw:
+        if isinstance(item, dict) and item.get("kind") == kind and isinstance(item.get(key), str):
+            return str(item[key])
+    return None
+
+
+def _account_annotation(
+    instr_name: str,
+    account: dict[str, Any],
+    accounts: list[dict[str, Any]],
+    imports: set[str],
+) -> str:
+    if account.get("isSigner"):
+        imports.add("Signer")
+        return "Signer"
+    matched = _match_account(str(account.get("name") or ""), accounts)
+    if matched is None:
+        imports.add("Pubkey")
+        return "Pubkey"
+    seed = _constraint(account, "seeds", "seed")
+    has_one = _constraint(account, "has_one", "field")
+    close = _constraint(account, "close", "account")
+    owner = _constraint(account, "owner", "account")
+    address = _constraint(account, "address", "pubkey")
+    if seed is not None:
+        imports.update({"Seeds", "Init"})
+        return f'Seeds[Init[{matched}], "{seed}"]'
+    if has_one is not None:
+        imports.update({"HasOne", "Mut"})
+        return f'HasOne[Mut[{matched}], "{has_one}"]'
+    if close is not None:
+        imports.update({"CloseTo", "Mut"})
+        return f"CloseTo[Mut[{matched}], {close}]"
+    if owner is not None:
+        imports.update({"Owner", "Mut"})
+        return f"Owner[Mut[{matched}], {owner}]"
+    if address is not None:
+        imports.update({"Address", "Mut"})
+        return f"Address[Mut[{matched}], {address}]"
+    if instr_name in _INIT_NAMES and account.get("isMut"):
+        imports.add("Init")
+        return f"Init[{matched}]"
+    if account.get("isMut"):
+        imports.add("Mut")
+        return f"Mut[{matched}]"
+    imports.add("Account")
+    return f"Account[{matched}]"
+
+
+def _instruction_block(
+    instr: dict[str, Any],
+    accounts: list[dict[str, Any]],
+    types: dict[str, dict[str, Any]],
+    imports: set[str],
+) -> str:
+    name = str(instr.get("name") or "instruction")
+    params: list[str] = []
+    for account in instr.get("accounts") or []:
+        if not isinstance(account, dict):
+            continue
+        param = str(account.get("name") or "account")
+        ann = _account_annotation(name, account, accounts, imports)
+        suffix = ""
+        if ann.startswith(_WRAPPERS):
+            suffix = "  # type: ignore[name-defined]  # noqa: F821"
+        params.append(f"    {param}: {ann},{suffix}")
+    for arg in instr.get("args") or []:
+        if not isinstance(arg, dict):
+            continue
+        param = str(arg.get("name") or "arg")
+        params.append(f"    {param}: {_annotation(arg.get('type'), types, imports)},")
+    lines = ["@instruction", f"def {name}("]
+    lines.extend(params)
+    lines.append(") -> None:")
+    lines.append(f'    """TODO: port {name}."""')
+    lines.append("    pass")
+    return "\n".join(lines)

pythsol/compiler/__init__.py

@@ -0,0 +1,39 @@
+"""PythSol compiler — front-end and toolchain modules.
+
+Pipeline: ``parse → subset → resolve → typecheck`` produce
+:class:`~pythsol.compiler.diagnostics.Diagnostic` objects; ``toolchain`` then
+compiles the generated C (Phase 3) to native SBF with clang + ld.lld.
+"""
+
+from __future__ import annotations
+
+from pythsol.compiler.diagnostics import PS4010, Diagnostic, PysolError
+from pythsol.compiler.front import check_source, check_tree
+from pythsol.compiler.toolchain import (
+    ToolchainPaths,
+    compile_to_sbf,
+    find_cargo_build_sbf,
+    find_clang,
+    find_lld,
+    find_solana_cli,
+    locate_platform_tools,
+    sbpf_compile_args,
+    sbpf_link_args,
+)
+
+__all__ = [
+    "PS4010",
+    "Diagnostic",
+    "PysolError",
+    "ToolchainPaths",
+    "check_source",
+    "check_tree",
+    "compile_to_sbf",
+    "find_cargo_build_sbf",
+    "find_clang",
+    "find_lld",
+    "find_solana_cli",
+    "locate_platform_tools",
+    "sbpf_compile_args",
+    "sbpf_link_args",
+]

pythsol/compiler/diagnostics.py

@@ -0,0 +1,130 @@
+"""Stable diagnostic codes and helpers shared by every compiler stage.
+
+Codes follow the pattern used in ``TRD.md`` §5.3:
+
+* ``PS1xxx`` — subset/parse
+* ``PS2xxx`` — type check
+* ``PS3xxx`` — semantic/aliasing
+* ``PS9xxx`` — internal compiler error (always a bug: report it)
+
+The registry below is written for Phase 2, but Phase 1 already hands back
+structured objects for toolchain errors.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One problem with a stable code and 1-based source position.
+
+    ``render()`` produces the clang-style string the CLI prints:
+
+        PS1003 program.py:4:5: unsupported statement: Try
+
+    The shape of :meth:`as_dict` is the ``--json`` contract; keep it additive.
+    """
+
+    code: str
+    message: str
+    file: str = "<program>"
+    line: int = 1
+    col: int = 1
+    fix: str | None = None
+
+    def render(self) -> str:
+        text = f"{self.code} {self.file}:{self.line}:{self.col}: {self.message}"
+        if self.fix:
+            return f"{text}\n  fix: {self.fix}"
+        return text
+
+    def position_key(self) -> tuple[int, int]:
+        return (self.line, self.col)
+
+    def as_dict(self) -> dict[str, str | int | None]:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "file": self.file,
+            "line": self.line,
+            "col": self.col,
+            "fix": self.fix,
+        }
+
+
+class PysolError(Exception):
+    """A structured compiler/toolchain error raised back to the CLI.
+
+    Not a dataclass: exceptions must accept ``__traceback__`` writes when
+    raised (a frozen dataclass blocks click's re-raise machinery).
+    """
+
+    def __init__(self, code: str, message: str, fix: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.fix = fix
+
+    def render(self) -> str:
+        text = f"{self.code}: {self.message}"
+        if self.fix:
+            return f"{text}\nsuggested fix: {self.fix}"
+        return text
+
+
+# ---------------------------------------------------------------------------
+# Subset / parse problems (PS1xxx)
+# ---------------------------------------------------------------------------
+PS1000 = "PS1000"  # unparseable syntax
+PS1001 = "PS1001"  # unsupported import
+PS1002 = "PS1002"  # floats/complex in program code
+PS1003 = "PS1003"  # unsupported statement (try/except, with, yield…)
+PS1004 = "PS1004"  # dynamic `import` or `__import__`
+PS1005 = "PS1005"  # `*args`/`**kwargs`/defaults on instruction functions are not callable.
+PS1006 = "PS1006"  # missing annotation on a parameter/field local.
+PS1007 = "PS1007"  # unsupported type annotation (unbounded containers, Any).
+PS1008 = "PS1008"  # unsupported attribute access / dynamic attribute assignment.
+PS1009 = "PS1009"  # unsupported operator (is, in, not-in on non-enums).
+PS1010 = "PS1010"  # unsupported call (dynamic callee).
+PS1011 = "PS1011"  # unsupported comprehension/generator.
+PS1012 = "PS1012"  # unsupported `class` (only @account/@error/@enum programs).
+
+# ---------------------------------------------------------------------------
+# Type-check problems (PS2xxx)
+# ---------------------------------------------------------------------------
+PS2000 = "PS2000"  # missing annotation on anything not inferable.
+PS2001 = "PS2001"  # unsupported/unknown type annotation.
+PS2002 = "PS2002"  # `float`/`complex` literal in program code.
+PS2003 = "PS2003"  # unbounded integers (int) are not allowed.
+PS2004 = "PS2004"  # bytes/str/list/tuple/dict/set in a program.
+PS2005 = "PS2005"  # unsupported assignment target.
+PS2006 = "PS2006"  # TypeError / unexpected operand.
+PS2007 = "PS2007"  # int width mismatch/overflow on constant expression.
+PS2008 = "PS2008"  # unsupported decorator target.
+
+# ---------------------------------------------------------------------------
+# Semantic / account-model problems (PS3xxx)
+# ---------------------------------------------------------------------------
+PS3000 = "PS3000"  # aliasing refusal (mutable data used for a live aliasing reference).
+PS3001 = "PS3001"  # unsupported constraint combination.
+
+# ---------------------------------------------------------------------------
+# Toolchain problems (PS40xx) — see toolchain.py for exact text.
+# ---------------------------------------------------------------------------
+PS4010 = "PS4010"
+
+# Model/elaboration problems (PS41xx) — raised by model.py when a type-checked
+# program still contains something the emitter model cannot represent.
+PS4001 = "PS4001"  # unsupported construct in the emitter model
+
+# Emitter problems (PS5xxx) — raised by emit.py while lowering an AST body.
+PS5001 = "PS5001"  # unsupported statement in an instruction body
+PS5002 = "PS5002"  # unsupported expression in an instruction body
+PS5003 = "PS5003"  # Init[...] without a `bump: u8` data parameter / payer signer
+
+# ---------------------------------------------------------------------------
+# Internal compiler errors (PS9xxx)
+# ---------------------------------------------------------------------------
+PS9000 = "PS9000"  # internal bug: unhandled construct in emitter.