gelang 0.1.0

package/python/pyeffic/golden.py

@@ -0,0 +1,348 @@
+"""Golden lowering corpus — proves emitted code stays put.
+
+Every emitter change is a risk: generated code can churn silently while still
+compiling and still producing the right answer. This module makes that churn
+visible.
+
+For each case under `tests/golden/<case>/`:
+
+    main.ge            the source
+    rust.golden        expected emitted Rust
+    cpp.golden         expected emitted C++
+    csharp.golden      ...
+    zig.golden
+    go.golden
+    kotlin.golden
+    expected.out       what the program must print
+
+Two independent checks:
+
+    lowering   emitted code == committed golden, byte for byte
+    behaviour  compiling and running the golden prints expected.out
+
+The lowering check proves we still emit the code we reviewed. The behaviour
+check proves that code still does what it did. Together they catch a
+regression that keeps compiling.
+
+This is the model bento uses for its TypeScript-to-Go corpus, and it is the
+same idea as Kotlin's `apiDump`/`apiCheck` applied to emitted code.
+
+Usage
+-----
+    ge golden --check            fail on any drift
+    ge golden --update           regenerate goldens (review the diff, then commit)
+    ge golden --check -v         show which cases drifted
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import Config, detect_compilers
+
+BACKENDS = ("rust", "cpp", "csharp", "zig", "go", "kotlin")
+
+_EMITTERS = {
+    "rust": "emit_rust",
+    "cpp": "emit_cpp",
+    "csharp": "emit_csharp",
+    "zig": "emit_zig",
+    "go": "emit_go",
+    "kotlin": "emit_kotlin",
+}
+
+
+def golden_root() -> Path:
+    """Where the corpus lives, relative to the repo root."""
+    here = Path(__file__).resolve().parent.parent
+    return here / "tests" / "golden"
+
+
+# ---------------------------------------------------------------------------
+# Emission
+# ---------------------------------------------------------------------------
+
+def emit_unit(source_path: Path, backend: str) -> str:
+    """Emit the whole compilation unit for one backend.
+
+    Uses the same import resolution and IR rename path as a real build, so a
+    golden reflects what a user would actually get.
+    """
+    from .emitters import (emit_cpp, emit_csharp, emit_go, emit_kotlin,
+                           emit_rust, emit_zig)
+    from .idents import rename_reserved_functions
+    from .modules import get_last_constants, get_last_preamble, resolve_imports
+
+    source = source_path.read_text(encoding="utf-8")
+    units, classes, _warnings = resolve_imports(source, source_path)
+    supported = [u for u in units if u.supported and u.body is not None]
+
+    # pin every function to the requested backend so the golden is stable
+    for u in supported:
+        u.forced_backend = backend
+    rename_reserved_functions(supported, {backend})
+
+    emit_fn = {
+        "rust": emit_rust, "cpp": emit_cpp, "csharp": emit_csharp,
+        "zig": emit_zig, "go": emit_go, "kotlin": emit_kotlin,
+    }[backend]
+    prog, _emitted = emit_fn(supported, entry="main", classes=classes,
+                             constants=get_last_constants(),
+                             preamble=get_last_preamble())
+    return prog
+
+
+def _normalise(text: str) -> str:
+    """Line endings normalised so goldens are platform-independent."""
+    return text.replace("\r\n", "\n").replace("\r", "\n")
+
+
+# ---------------------------------------------------------------------------
+# Results
+# ---------------------------------------------------------------------------
+
+@dataclass
+class GoldenProblem:
+    case: str
+    kind: str      # "lowering" | "behaviour" | "missing" | "unexpected"
+    detail: str
+
+
+@dataclass
+class GoldenReport:
+    cases: list[Path] = field(default_factory=list)
+    problems: list[GoldenProblem] = field(default_factory=list)
+    updated: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.problems
+
+    @property
+    def checked(self) -> int:
+        return len(self.cases)
+
+
+# ---------------------------------------------------------------------------
+# Case discovery
+# ---------------------------------------------------------------------------
+
+def find_cases(root: Path | None = None) -> list[Path]:
+    """Every golden case directory (one that contains a source file)."""
+    root = root or golden_root()
+    if not root.is_dir():
+        return []
+    out: list[Path] = []
+    for d in sorted(root.iterdir()):
+        if not d.is_dir():
+            continue
+        for name in ("main.ge", "main.ge.py", "main.ge.ts"):
+            if (d / name).is_file():
+                out.append(d)
+                break
+    return out
+
+
+def case_source(case_dir: Path) -> Path:
+    for name in ("main.ge", "main.ge.py", "main.ge.ts"):
+        p = case_dir / name
+        if p.is_file():
+            return p
+    raise FileNotFoundError(f"no source in {case_dir}")
+
+
+# ---------------------------------------------------------------------------
+# Check / update
+# ---------------------------------------------------------------------------
+
+def _golden_path(case_dir: Path, backend: str) -> Path:
+    return case_dir / f"{backend}.golden"
+
+
+def check_case(case_dir: Path, backends: tuple[str, ...] = BACKENDS,
+               run: bool = True) -> list[GoldenProblem]:
+    """Compare emitted code with the committed goldens for one case."""
+    problems: list[GoldenProblem] = []
+    src = case_source(case_dir)
+    name = case_dir.name
+
+    for backend in backends:
+        gpath = _golden_path(case_dir, backend)
+        try:
+            emitted = _normalise(emit_unit(src, backend))
+        except Exception as exc:
+            problems.append(GoldenProblem(
+                name, "lowering", f"{backend}: emission failed: {exc}"))
+            continue
+
+        if not gpath.exists():
+            problems.append(GoldenProblem(
+                name, "missing", f"{backend}.golden is absent "
+                                 f"(run: ge golden --update)"))
+            continue
+
+        expected = _normalise(gpath.read_text(encoding="utf-8"))
+        if emitted != expected:
+            problems.append(GoldenProblem(
+                name, "lowering",
+                f"{backend}.golden drifted — review with `ge golden --update` "
+                f"then commit the diff"))
+    return problems
+
+
+def update_case(case_dir: Path, backends: tuple[str, ...] = BACKENDS) -> list[str]:
+    """Regenerate the goldens for one case. Returns the files written."""
+    src = case_source(case_dir)
+    written: list[str] = []
+    for backend in backends:
+        try:
+            emitted = _normalise(emit_unit(src, backend))
+        except Exception:
+            continue
+        gpath = _golden_path(case_dir, backend)
+        old = gpath.read_text(encoding="utf-8") if gpath.exists() else None
+        if _normalise(old or "") != emitted:
+            gpath.write_text(emitted, encoding="utf-8")
+            written.append(f"{case_dir.name}/{backend}.golden")
+    return written
+
+
+def _check_behaviour(case_dir: Path, timeout: int = 90) -> list[GoldenProblem]:
+    """Compile and run the source; it must print expected.out."""
+    expected_path = case_dir / "expected.out"
+    if not expected_path.exists():
+        return [GoldenProblem(case_dir.name, "missing",
+                              "expected.out is absent")]
+    expected = _normalise(expected_path.read_text(encoding="utf-8")).strip()
+
+    from .pipeline import build
+    from .config import Config
+
+    with __import__("tempfile").TemporaryDirectory() as td:
+        cfg = Config(out_dir=Path(td), target="desktop", do_research=False)
+        try:
+            report = build(case_source(case_dir), cfg, entry="main")
+        except Exception as exc:
+            return [GoldenProblem(case_dir.name, "behaviour",
+                                  f"build raised: {exc}")]
+        if report.errors.has_errors():
+            first = report.errors.diagnostics[0]
+            return [GoldenProblem(
+                case_dir.name, "behaviour",
+                f"build failed: {getattr(first, 'message', first)}")]
+
+        cr = report.rust_compile or report.cpp_compile
+        if cr is None or not cr.ok or not cr.exe:
+            return [GoldenProblem(case_dir.name, "behaviour",
+                                  "no runnable binary produced")]
+        try:
+            proc = subprocess.run([str(cr.exe)], capture_output=True,
+                                  text=True, timeout=timeout)
+        except subprocess.TimeoutExpired:
+            return [GoldenProblem(case_dir.name, "behaviour",
+                                  f"timed out after {timeout}s")]
+        got = _normalise(proc.stdout).strip()
+        if got != expected:
+            return [GoldenProblem(
+                case_dir.name, "behaviour",
+                f"output changed\n    expected: {expected!r}\n"
+                f"    actual  : {got!r}")]
+    return []
+
+
+def check(root: Path | None = None, backends: tuple[str, ...] = BACKENDS,
+          behaviour: bool = True) -> GoldenReport:
+    """Check every case."""
+    report = GoldenReport()
+    for case_dir in find_cases(root):
+        report.cases.append(case_dir)
+        report.problems.extend(check_case(case_dir, backends))
+        if behaviour:
+            report.problems.extend(_check_behaviour(case_dir))
+    return report
+
+
+def update(root: Path | None = None,
+           backends: tuple[str, ...] = BACKENDS) -> GoldenReport:
+    """Regenerate every golden."""
+    report = GoldenReport()
+    for case_dir in find_cases(root):
+        report.cases.append(case_dir)
+        report.updated.extend(update_case(case_dir, backends))
+    return report
+
+
+def available(backends: tuple[str, ...] = BACKENDS) -> tuple[str, ...]:
+    """Backends whose toolchain is installed (behaviour checks need these)."""
+    info = detect_compilers()
+    have = {
+        "rust": bool(info.rustc), "cpp": bool(info.cpp),
+        "csharp": bool(info.dotnet), "zig": bool(info.zig),
+        "go": bool(info.go), "kotlin": bool(info.kotlinc),
+    }
+    return tuple(b for b in backends if have.get(b))
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    p = argparse.ArgumentParser(
+        prog="ge golden",
+        description="Check or regenerate the golden lowering corpus")
+    p.add_argument("--check", action="store_true",
+                   help="fail if emitted code differs from the committed golden")
+    p.add_argument("--update", action="store_true",
+                   help="regenerate goldens from the current emitters")
+    p.add_argument("--no-behaviour", action="store_true",
+                   help="skip the compile-and-run check")
+    p.add_argument("--backends", default=None,
+                   help="comma-separated subset (default: all)")
+    p.add_argument("-v", "--verbose", action="store_true")
+    args = p.parse_args(argv)
+
+    backends = BACKENDS
+    if args.backends:
+        backends = tuple(b.strip() for b in args.backends.split(",") if b.strip())
+
+    root = golden_root()
+    if not root.is_dir():
+        print(f"error: no golden corpus at {root}", file=sys.stderr)
+        return 2
+
+    if args.update:
+        report = update(root, backends)
+        print("GE golden corpus — update")
+        print(f"  cases  : {report.checked}")
+        print(f"  written: {len(report.updated)}")
+        for name in report.updated:
+            print(f"    {name}")
+        if not report.updated:
+            print("  (no changes)")
+        print()
+        print("review the diff, then commit it")
+        return 0
+
+    report = check(root, backends, behaviour=not args.no_behaviour)
+    print("GE golden corpus — check")
+    print(f"  cases   : {report.checked}")
+    print(f"  backends: {', '.join(backends)}")
+    print()
+
+    if report.ok:
+        print("all goldens match and every case still prints its expected output")
+        return 0
+
+    print(f"{len(report.problems)} problem(s):")
+    for prob in report.problems:
+        print(f"  [{prob.kind}] {prob.case}: {prob.detail}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/pyeffic/idents.py

@@ -0,0 +1,206 @@
+"""Identifier safety across target languages.
+
+GE identifiers are Python names, so they may collide with a target
+language's reserved words (`double` is a C++ type, `base` is a C# keyword,
+`match` is a Rust keyword, ...).
+
+Two kinds of identifier need different treatment:
+
+* **Function names** can cross the C ABI (Rust calling a C++ function), so
+  every side must agree on the symbol. These are renamed once in the shared
+  IR by `rename_reserved_functions`, before any emitter runs.
+* **Locals and parameters** never cross the ABI, so each backend escapes
+  them in its own idiom (`@base` in C#, `r#match` in Rust, `base_` in C++
+  which has no escape syntax).
+"""
+from __future__ import annotations
+
+from .analyzer import FuncUnit
+
+# ---------------------------------------------------------------------------
+# Reserved word sets
+# ---------------------------------------------------------------------------
+
+CPP_RESERVED = {
+    # keywords
+    "alignas", "alignof", "and", "and_eq", "asm", "auto", "bitand", "bitor",
+    "bool", "break", "case", "catch", "char", "char8_t", "char16_t",
+    "char32_t", "class", "compl", "concept", "const", "consteval",
+    "constexpr", "constinit", "const_cast", "continue", "co_await",
+    "co_return", "co_yield", "decltype", "default", "delete", "do", "double",
+    "dynamic_cast", "else", "enum", "explicit", "export", "extern", "false",
+    "float", "for", "friend", "goto", "if", "inline", "int", "long",
+    "mutable", "namespace", "new", "noexcept", "not", "not_eq", "nullptr",
+    "operator", "or", "or_eq", "private", "protected", "public", "register",
+    "reinterpret_cast", "requires", "return", "short", "signed", "sizeof",
+    "static", "static_assert", "static_cast", "struct", "switch", "template",
+    "this", "thread_local", "throw", "true", "try", "typedef", "typeid",
+    "typename", "union", "unsigned", "using", "virtual", "void", "volatile",
+    "wchar_t", "while", "xor", "xor_eq",
+    # core library type names: a function with one of these names would
+    # collide with the type itself
+    "std", "string", "vector", "map", "tuple", "pair", "set",
+}
+
+RUST_RESERVED = {
+    "as", "break", "const", "continue", "crate", "dyn", "else", "enum",
+    "extern", "false", "fn", "for", "if", "impl", "in", "let", "loop",
+    "match", "mod", "move", "mut", "pub", "ref", "return", "self", "Self",
+    "static", "struct", "super", "trait", "true", "type", "unsafe", "use",
+    "where", "while", "async", "await", "abstract", "become", "box", "do",
+    "final", "macro", "override", "priv", "try", "typeof", "unsized",
+    "virtual", "yield",
+    # core prelude type names
+    "String", "Vec", "Box", "Option", "Result", "Some", "None", "Ok", "Err",
+}
+
+CSHARP_RESERVED = {
+    "abstract", "as", "base", "bool", "break", "byte", "case", "catch",
+    "char", "checked", "class", "const", "continue", "decimal", "default",
+    "delegate", "do", "double", "else", "enum", "event", "explicit",
+    "extern", "false", "finally", "fixed", "float", "for", "foreach", "goto",
+    "if", "implicit", "in", "int", "interface", "internal", "is", "lock",
+    "long", "namespace", "new", "null", "object", "operator", "out",
+    "override", "params", "private", "protected", "public", "readonly",
+    "ref", "return", "sbyte", "sealed", "short", "sizeof", "stackalloc",
+    "static", "string", "struct", "switch", "this", "throw", "true", "try",
+    "typeof", "uint", "ulong", "unchecked", "unsafe", "ushort", "using",
+    "virtual", "void", "volatile", "while",
+    # core library type names
+    "Console", "Math", "Convert", "String", "Object",
+}
+
+GO_RESERVED = {
+    "break", "case", "chan", "const", "continue", "default", "defer",
+    "else", "fallthrough", "for", "func", "go", "goto", "if", "import",
+    "interface", "map", "package", "range", "return", "select", "struct",
+    "switch", "type", "var",
+    # core prelude type names
+    "int", "int64", "float64", "string", "bool", "byte", "rune",
+}
+
+KOTLIN_RESERVED = {
+    "as", "break", "class", "continue", "do", "else", "false", "for", "fun",
+    "if", "in", "interface", "is", "null", "object", "package", "return",
+    "super", "this", "throw", "true", "try", "typealias", "typeof", "val",
+    "var", "when", "while",
+    # core prelude type names
+    "Int", "Long", "Double", "String", "Boolean", "List", "Array", "Unit",
+}
+
+ZIG_RESERVED = {
+    "align", "allowzero", "and", "anyframe", "anytype", "asm", "async",
+    "await", "break", "catch", "comptime", "const", "continue", "defer",
+    "else", "enum", "errdefer", "error", "export", "extern", "fn", "for",
+    "if", "inline", "noalias", "nosuspend", "opaque", "or", "orelse",
+    "packed", "pub", "resume", "return", "linksection", "struct", "suspend",
+    "switch", "test", "threadlocal", "try", "union", "unreachable",
+    "usingnamespace", "var", "volatile", "while",
+    # core prelude type names
+    "i64", "f64", "bool", "u8", "usize", "std",
+}
+
+#: backend name -> reserved words
+RESERVED: dict[str, set[str]] = {
+    "cpp": CPP_RESERVED,
+    "rust": RUST_RESERVED,
+    "csharp": CSHARP_RESERVED,
+    "go": GO_RESERVED,
+    "kotlin": KOTLIN_RESERVED,
+    "zig": ZIG_RESERVED,
+}
+
+#: how each backend escapes a local/parameter name
+ESCAPE_STYLE = {
+    "csharp": "prefix_at",   # @base
+    "rust": "prefix_r",      # r#match
+    "cpp": "suffix",         # base_  (no escape syntax in C++)
+    "go": "suffix",
+    "kotlin": "suffix",
+    "zig": "suffix",
+}
+
+
+def is_reserved(name: str, backend) -> bool:
+    """True if `name` is reserved by the given backend (or any of several)."""
+    if isinstance(backend, str):
+        return name in RESERVED.get(backend, set())
+    return any(name in RESERVED.get(b, set()) for b in backend)
+
+
+def escape_local(name: str, backend: str) -> str:
+    """Escape a local/parameter name in the backend's idiom."""
+    if not is_reserved(name, backend):
+        return name
+    style = ESCAPE_STYLE.get(backend, "suffix")
+    if style == "prefix_at":
+        return "@" + name
+    if style == "prefix_r":
+        return "r#" + name
+    return name + "_"
+
+
+def safe_function_name(name: str, backends) -> str:
+    """A function name that is safe in every one of `backends`.
+
+    Function symbols can cross the C ABI, so the rename has to be decided
+    once, for all backends at the same time.
+    """
+    for backend in backends:
+        if is_reserved(name, backend):
+            return name + "_"
+    return name
+
+
+# ---------------------------------------------------------------------------
+# IR-level rename
+# ---------------------------------------------------------------------------
+
+def rename_reserved_functions(units: list[FuncUnit], backends) -> dict[str, str]:
+    """Rename functions whose names collide with a target keyword.
+
+    Applies the rename to definitions *and* call sites across every unit, so
+    the whole program — including cross-backend `extern "C"` declarations —
+    agrees on one symbol. Returns the {old: new} map for reporting.
+    """
+    import ast
+
+    # `main` is the entry point: emitters resolve it by name, so it is never
+    # renamed. (It is not in the reserved sets either.)
+    collisions = {u.name for u in units
+                  if u.name != "main" and is_reserved(u.name, backends)}
+    if not collisions:
+        return {}
+    mapping = {name: safe_function_name(name, backends) for name in collisions}
+
+    # rename definitions
+    for u in units:
+        if u.name in mapping:
+            u.name = mapping[u.name]
+
+    # rename call sites and any reference
+    class _Renamer(ast.NodeTransformer):
+        def visit_Name(self, node: ast.Name) -> ast.AST:
+            if node.id in mapping:
+                node.id = mapping[node.id]
+            return node
+
+        def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.AST:
+            if node.name in mapping:
+                node.name = mapping[node.name]
+            self.generic_visit(node)
+            return node
+
+    renamer = _Renamer()
+    for u in units:
+        body = u.body
+        if body is None:
+            continue
+        # FuncUnit.body is the function node in some paths and the statement
+        # list in others; normalise before rewriting.
+        if isinstance(body, ast.AST):
+            u.body = renamer.visit(body)
+        elif isinstance(body, list):
+            u.body = [renamer.visit(stmt) for stmt in body]
+
+    return mapping