serpentine-lang 0.4.0__tar.gz

serpentine_lang-0.4.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: serpentine-lang
+Version: 0.4.0
+Summary: Serpentine: AOT compiler for an ownership-disciplined Python subset (serp CLI)
+Author: Serpentine contributors
+License: MIT
+Project-URL: Homepage, https://github.com/avijitbhuin21/Serpentine
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: llvm
+Requires-Dist: llvmlite>=0.44; extra == "llvm"
+
+# serpentine-lang
+
+The Serpentine compiler (`serp` CLI). Phase-1 walking skeleton:
+
+- `serp check entry.py` — frontend, type checker, SIR ownership analyses; exits 0/1.
+- `serp build entry.py [-o out] [--keep-rust]` — Backend A: transpiles to Rust and invokes
+  `rustc` to produce a native binary with no libpython dependency.
+
+The Tier-0 language is specified in the repository's `SPEC.md`; the test corpus under
+`tests/` is the executable half of that spec.

serpentine_lang-0.4.0/README.md

@@ -0,0 +1,10 @@
+# serpentine-lang
+
+The Serpentine compiler (`serp` CLI). Phase-1 walking skeleton:
+
+- `serp check entry.py` — frontend, type checker, SIR ownership analyses; exits 0/1.
+- `serp build entry.py [-o out] [--keep-rust]` — Backend A: transpiles to Rust and invokes
+  `rustc` to produce a native binary with no libpython dependency.
+
+The Tier-0 language is specified in the repository's `SPEC.md`; the test corpus under
+`tests/` is the executable half of that spec.

serpentine_lang-0.4.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "serpentine-lang"
+version = "0.4.0"
+description = "Serpentine: AOT compiler for an ownership-disciplined Python subset (serp CLI)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Serpentine contributors" }]
+
+[project.urls]
+Homepage = "https://github.com/avijitbhuin21/Serpentine"
+
+[project.optional-dependencies]
+llvm = ["llvmlite>=0.44"]
+
+[project.scripts]
+serp = "serpentine_lang.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+serpentine_lang = ["prelude.rs"]

serpentine_lang-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

serpentine_lang-0.4.0/src/serpentine_lang/__init__.py

@@ -0,0 +1,3 @@
+"""Serpentine compiler package."""
+
+__version__ = "0.1.0"

serpentine_lang-0.4.0/src/serpentine_lang/api.py

@@ -0,0 +1,30 @@
+"""Checker-as-library API (RESEARCH.md §5.13): structured diagnostics for tooling.
+
+This is the supported programmatic surface for editors, CI hooks, and the LSP
+server. It never prints and never exits; it returns `Diagnostic` values.
+"""
+
+from pathlib import Path
+
+from .cli import run_check
+from .diagnostics import Diagnostic, Reporter, SerpError
+
+
+def check_file(path: str | Path, overlay: dict[str, str] | None = None) -> list[Diagnostic]:
+    """Check the program rooted at `path`; return all diagnostics (empty = clean).
+
+    `overlay` maps resolved file paths to in-memory contents that shadow the
+    on-disk text, so unsaved editor buffers can be checked.
+    """
+    rep = Reporter()
+    try:
+        run_check(Path(path), rep, overlay=overlay)
+    except SerpError:
+        pass
+    return list(rep.diags)
+
+
+def check_source(path: str | Path, text: str) -> list[Diagnostic]:
+    """Check a single in-memory buffer as the program entry point."""
+    resolved = str(Path(path).resolve())
+    return check_file(path, overlay={resolved: text})

serpentine_lang-0.4.0/src/serpentine_lang/borrowck.py

@@ -0,0 +1,171 @@
+"""Ownership analyses over SIR: initialized-places dataflow + lexical loan checks.
+
+Initialized-places is a forward may/must dataflow with a worklist (fixed point),
+so moves inside loop bodies are caught at the loop head (SPEC.md J8). Places are
+field-sensitive to one level ("x" and "x.f"): moving x.f leaves x.g usable but
+the whole x unusable until x.f is re-assigned. Loans are lexical for-loop
+regions recorded on each instruction during lowering.
+"""
+
+import ast
+from .diagnostics import Reporter, Span
+from .sir import FuncSIR
+
+UNINIT = 0
+INIT = 1
+MOVED = 2
+MAYBE = 3   # conflicting states at a join: maybe-moved / maybe-uninit
+
+
+def _merge(a: int, b: int) -> int:
+    if a == b:
+        return a
+    return MAYBE
+
+
+def _root(var: str) -> str:
+    return var.split(".", 1)[0]
+
+
+def _apply(kind: str, var: str, state: dict, all_vars: list[str]) -> None:
+    """Advance the dataflow state over one instruction."""
+    if kind == "def":
+        state[var] = INIT
+        if "." not in var:
+            for v in all_vars:
+                if v.startswith(var + "."):
+                    state[v] = INIT
+    elif kind == "field_def":
+        state[var] = INIT
+    elif kind in ("move", "drop"):
+        state[var] = MOVED
+
+
+def _eff(state: dict, var: str) -> int:
+    """Effective state of a place: an untouched field inherits its root's state."""
+    s = state.get(var, UNINIT)
+    if "." in var and s == UNINIT:
+        return state.get(_root(var), UNINIT)
+    return s
+
+
+def check_function(sir: FuncSIR, rep: Reporter, file: str) -> None:
+    """Run both analyses on one function and report diagnostics."""
+    all_vars = sorted({i.var for b in sir.blocks for i in b.instrs})
+    params = {p.name for p in sir.sig.params}
+    entry_state = {}
+    for v in all_vars:
+        if _root(v) in params:
+            entry_state[v] = INIT
+        else:
+            entry_state[v] = UNINIT
+
+    in_states: dict[int, dict[str, int] | None] = {b.id: None for b in sir.blocks}
+    in_states[sir.entry] = dict(entry_state)
+    work = [sir.entry]
+    while work:
+        bid = work.pop()
+        state = dict(in_states[bid])  # type: ignore[arg-type]
+        block = sir.blocks[bid]
+        for instr in block.instrs:
+            _apply(instr.kind, instr.var, state, all_vars)
+        for succ in block.succs:
+            merged = state if in_states[succ] is None else {
+                v: _merge(in_states[succ].get(v, UNINIT), state.get(v, UNINIT))  # type: ignore[union-attr]
+                for v in all_vars
+            }
+            if merged != in_states[succ]:
+                in_states[succ] = dict(merged)
+                work.append(succ)
+
+    move_sites: dict[str, Span] = {}
+    for block in sir.blocks:
+        for instr in block.instrs:
+            if instr.kind == "move" and instr.var not in move_sites:
+                move_sites[instr.var] = _span(instr.node, file)
+
+    for block in sir.blocks:
+        if in_states[block.id] is None:
+            continue
+        state = dict(in_states[block.id])  # type: ignore[arg-type]
+        for instr in block.instrs:
+            _check_instr(instr, state, rep, file, all_vars, move_sites)
+            _apply(instr.kind, instr.var, state, all_vars)
+
+
+def _span(node: ast.AST, file: str) -> Span:
+    return Span(file, getattr(node, "lineno", 1), getattr(node, "col_offset", 0),
+                getattr(node, "end_col_offset", None))
+
+
+def _moved_secondary(var: str, move_sites: dict) -> list:
+    site = move_sites.get(var)
+    return [(site, f"'{var}' moved here")] if site is not None else []
+
+
+def _check_instr(instr, state: dict, rep: Reporter, file: str,
+                 all_vars: list[str], move_sites: dict) -> None:
+    var = instr.var
+    span = _span(instr.node, file)
+    if instr.kind in ("use", "mut_use", "move"):
+        cur = _eff(state, var)
+        if cur == MOVED:
+            rep.error("SE001", "use-after-move",
+                      f"use of moved value '{var}'", span,
+                      label="value was moved before this use",
+                      secondary=_moved_secondary(var, move_sites),
+                      help=f"re-initialize '{var}' before this point, or borrow instead "
+                           f"of moving")
+        elif cur == MAYBE:
+            rep.error("SE001", "use-after-move",
+                      f"use of possibly-moved value '{var}' — it is moved on some "
+                      f"paths reaching this point", span,
+                      label="maybe-moved here",
+                      secondary=_moved_secondary(var, move_sites),
+                      help=f"assign '{var}' on every path (or none) before this use")
+        elif "." not in var:
+            # Whole-value use: every field must still be present (partial moves).
+            for v in all_vars:
+                if v.startswith(var + ".") and state.get(v, UNINIT) in (MOVED, MAYBE):
+                    fieldname = v.split(".", 1)[1]
+                    rep.error("SE001", "use-after-move",
+                              f"use of partially moved value '{var}' — field "
+                              f"'{fieldname}' was moved out", span,
+                              label=f"'{v}' is gone here",
+                              secondary=_moved_secondary(v, move_sites),
+                              help=f"re-assign '{v}' before using '{var}' as a whole")
+                    break
+        if "." in var:
+            root_state = state.get(_root(var), UNINIT)
+            if root_state in (MOVED, MAYBE):
+                rep.error("SE001", "use-after-move",
+                          f"use of field '{var}' of moved value '{_root(var)}'", span,
+                          label="the containing value was moved",
+                          secondary=_moved_secondary(_root(var), move_sites))
+    if instr.kind == "field_def":
+        root_state = state.get(_root(var), UNINIT)
+        if root_state in (MOVED, MAYBE):
+            rep.error("SE001", "use-after-move",
+                      f"cannot assign to field '{var}' of moved value '{_root(var)}'",
+                      span, label="the containing value was moved",
+                      secondary=_moved_secondary(_root(var), move_sites),
+                      help=f"re-initialize '{_root(var)}' as a whole first")
+    if instr.kind in ("mut_use", "move", "def", "field_def"):
+        for (loan_var, _kind) in instr.loans:
+            if loan_var == _root(var):
+                if instr.kind == "move":
+                    rep.error("SE005", "move-while-borrowed",
+                              f"cannot move '{var}' while it is borrowed by the "
+                              f"enclosing for loop", span,
+                              label="borrowed for the whole loop body")
+                else:
+                    rep.error("SE004", "conflicting-borrow",
+                              f"cannot mutate '{var}' while it is borrowed by the "
+                              f"enclosing for loop", span,
+                              label="the loop holds a Ref borrow of it")
+
+
+def check_program(sirs: dict, rep: Reporter, files: dict[str, str]) -> None:
+    """Run ownership analyses on every function in the program."""
+    for (mod, _fname), sir in sirs.items():
+        check_function(sir, rep, files[mod])

serpentine_lang-0.4.0/src/serpentine_lang/cli.py

@@ -0,0 +1,151 @@
+"""The serp CLI: check and build subcommands."""
+
+import argparse
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from .borrowck import check_program
+from .diagnostics import Reporter, SerpError
+from .frontend import load_program
+from .rustgen import CodegenError, generate_rust
+from .sir import lower_program
+from .typecheck import TypeChecker
+
+
+def run_check(entry: Path, rep: Reporter, dump_sir: bool = False,
+              overlay: dict[str, str] | None = None):
+    """Run the full static pipeline; returns the TypeChecker on success."""
+    program = load_program(entry, rep, overlay)
+    tc = TypeChecker(program, rep)
+    tc.run()
+    sirs = lower_program(tc)
+    files = {m.name: str(m.path) for m in program.modules.values()}
+    check_program(sirs, rep, files)
+    if rep.diags:
+        raise SerpError(rep.diags)
+    if dump_sir:
+        for sir in sirs.values():
+            print(sir.dump())
+    return tc
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    """serp check: report diagnostics, exit 0/1."""
+    rep = Reporter()
+    try:
+        run_check(Path(args.file), rep, dump_sir=args.dump_sir)
+    except SerpError:
+        print(rep.render_all(), file=sys.stderr)
+        n = len({(d.code, d.span.line, d.span.col) for d in rep.diags})
+        print(f"\nserp: {n} error(s)", file=sys.stderr)
+        return 1
+    print(f"serp: OK ({args.file})")
+    return 0
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    """serp build: check, transpile to Rust, invoke rustc."""
+    rep = Reporter()
+    try:
+        tc = run_check(Path(args.file), rep)
+    except SerpError:
+        print(rep.render_all(), file=sys.stderr)
+        return 1
+    try:
+        rust_src = generate_rust(tc)
+    except CodegenError as exc:
+        print(f"serp: internal codegen error: {exc}", file=sys.stderr)
+        return 2
+
+    entry = Path(args.file).resolve()
+    out = Path(args.output) if args.output else entry.with_suffix("")
+    if sys.platform == "win32" and out.suffix != ".exe":
+        out = out.with_suffix(".exe")
+
+    rustc = shutil.which("rustc")
+    if rustc is None:
+        print("serp: rustc not found on PATH — install Rust to use `serp build`", file=sys.stderr)
+        return 2
+
+    rs_dir = Path(tempfile.mkdtemp(prefix="serp_build_"))
+    rs_file = rs_dir / f"{entry.stem}.rs"
+    rs_file.write_text(rust_src, encoding="utf-8")
+    if args.keep_rust:
+        keep = entry.with_suffix(".rs")
+        keep.write_text(rust_src, encoding="utf-8")
+        print(f"serp: rust source kept at {keep}")
+
+    opt = "0" if args.debug else "2"
+    proc = subprocess.run(
+        [rustc, "--edition", "2021", "-C", f"opt-level={opt}", "-o", str(out), str(rs_file)],
+        capture_output=True, text=True, encoding="utf-8", errors="replace",
+    )
+    if proc.returncode != 0:
+        print("serp: rustc rejected the generated program (checker/oracle disagreement):",
+              file=sys.stderr)
+        print(proc.stderr, file=sys.stderr)
+        return 2
+    print(f"serp: built {out}")
+    return 0
+
+
+def cmd_llvm(args: argparse.Namespace) -> int:
+    """serp llvm: check, lower to LLVM IR (Backend B numeric core), JIT-run or dump IR."""
+    from .llvmgen import LLVMUnsupported, generate_llvm, run_llvm
+    rep = Reporter()
+    try:
+        tc = run_check(Path(args.file), rep)
+    except SerpError:
+        print(rep.render_all(), file=sys.stderr)
+        return 1
+    try:
+        if args.emit_ir:
+            print(generate_llvm(tc))
+            return 0
+        return run_llvm(tc)
+    except LLVMUnsupported as exc:
+        print(f"serp: program is outside the LLVM numeric core ({exc}) — "
+              f"use `serp build` (Rust backend)", file=sys.stderr)
+        return 3
+
+
+def cmd_lsp(args: argparse.Namespace) -> int:
+    """serp lsp: run the Language Server Protocol server on stdio."""
+    from .lsp import serve_stdio
+    return serve_stdio()
+
+
+def main() -> int:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(prog="serp", description="Serpentine compiler")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_check = sub.add_parser("check", help="type- and borrow-check a program")
+    p_check.add_argument("file")
+    p_check.add_argument("--dump-sir", action="store_true", help="print the SIR after checking")
+    p_check.set_defaults(func=cmd_check)
+
+    p_build = sub.add_parser("build", help="compile to a native binary via Rust")
+    p_build.add_argument("file")
+    p_build.add_argument("-o", "--output", default=None)
+    p_build.add_argument("--keep-rust", action="store_true", help="write the generated .rs next to the source")
+    p_build.add_argument("--debug", action="store_true", help="opt-level=0 for faster builds")
+    p_build.set_defaults(func=cmd_build)
+
+    p_llvm = sub.add_parser("llvm", help="run via the LLVM backend (numeric core, JIT)")
+    p_llvm.add_argument("file")
+    p_llvm.add_argument("--emit-ir", action="store_true", help="print LLVM IR instead of running")
+    p_llvm.set_defaults(func=cmd_llvm)
+
+    p_lsp = sub.add_parser("lsp", help="run the LSP server on stdio (editor diagnostics)")
+    p_lsp.set_defaults(func=cmd_lsp)
+
+    args = parser.parse_args()
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

serpentine_lang-0.4.0/src/serpentine_lang/diagnostics.py

@@ -0,0 +1,95 @@
+"""Diagnostics v1: stable error codes, source spans, primary labels."""
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Span:
+    """A source location: file, 1-indexed line, 0-indexed column."""
+
+    file: str
+    line: int
+    col: int
+    end_col: int | None = None
+
+
+@dataclass
+class Diagnostic:
+    """A single checker error with its stable code and primary label."""
+
+    code: str
+    name: str
+    message: str
+    span: Span
+    label: str = ""
+    secondary: list = field(default_factory=list)   # list[(Span, str)]
+    help: str = ""
+
+    def render(self, source_lines: dict[str, list[str]] | None = None) -> str:
+        """Render the diagnostic in rustc-style layout with source lines and carets."""
+        out = [f"error[{self.code}]: {self.message}"]
+        out.append(f"  --> {self.span.file}:{self.span.line}:{self.span.col + 1}")
+        self._render_snippet(out, self.span, self.label, "^", source_lines)
+        for (span, label) in self.secondary:
+            out.append(f"  --> {span.file}:{span.line}:{span.col + 1}")
+            self._render_snippet(out, span, label, "-", source_lines)
+        if self.help:
+            out.append(f"  help: {self.help}")
+        return "\n".join(out)
+
+    def _render_snippet(self, out: list[str], span: Span, label: str, marker: str,
+                        source_lines: dict[str, list[str]] | None) -> None:
+        lines = (source_lines or {}).get(span.file)
+        if lines and 1 <= span.line <= len(lines):
+            src = lines[span.line - 1].rstrip("\n")
+            gutter = str(span.line)
+            pad = " " * len(gutter)
+            out.append(f"{pad} |")
+            out.append(f"{gutter} | {src}")
+            width = max(1, (span.end_col or (span.col + 1)) - span.col)
+            carets = " " * span.col + marker * width
+            suffix = f" {label}" if label else ""
+            out.append(f"{pad} | {carets}{suffix}")
+
+
+class SerpError(Exception):
+    """Raised to abort compilation with one or more diagnostics."""
+
+    def __init__(self, diags: list[Diagnostic]):
+        super().__init__(diags[0].message if diags else "compile error")
+        self.diags = diags
+
+
+@dataclass
+class Reporter:
+    """Collects diagnostics and source text for rendering."""
+
+    diags: list[Diagnostic] = field(default_factory=list)
+    sources: dict[str, list[str]] = field(default_factory=dict)
+
+    def add_source(self, file: str, text: str) -> None:
+        """Register a file's source text for diagnostic rendering."""
+        self.sources[file] = text.splitlines()
+
+    def error(self, code: str, name: str, message: str, span: Span, label: str = "",
+              secondary: list | None = None, help: str = "") -> None:
+        """Record one diagnostic."""
+        self.diags.append(Diagnostic(code, name, message, span, label,
+                                     secondary or [], help))
+
+    def fatal(self, code: str, name: str, message: str, span: Span, label: str = "",
+              secondary: list | None = None, help: str = "") -> None:
+        """Record one diagnostic and abort compilation immediately."""
+        self.error(code, name, message, span, label, secondary, help)
+        raise SerpError(self.diags)
+
+    def render_all(self) -> str:
+        """Render every collected diagnostic, deduplicated and in source order."""
+        seen = set()
+        ordered = []
+        for d in sorted(self.diags, key=lambda d: (d.span.file, d.span.line, d.span.col, d.code)):
+            key = (d.code, d.span.file, d.span.line, d.span.col, d.message)
+            if key not in seen:
+                seen.add(key)
+                ordered.append(d)
+        return "\n\n".join(d.render(self.sources) for d in ordered)