godcode-engine 4.0.0__py3-none-any.whl

godcode/__init__.py

@@ -0,0 +1,86 @@
+"""God Code v3.0 — the language of divine computation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+__version__ = "4.0.0"
+
+
+@dataclass
+class RunResult:
+    """The outcome of running God Code from a host program.
+
+    ``output`` is the captured REVEAL output (lines joined with ``\\n``);
+    ``return_value`` is the value of a top-level ``RETURN`` (if the scroll
+    ascends that way) or of the last expression statement evaluated, else
+    ``None``; ``error`` is the divine error message (with line number) when
+    the run failed; ``ok`` tells whether the run completed.
+    """
+
+    output: str = ""
+    return_value: Any = None
+    error: str | None = None
+    ok: bool = False
+
+
+def run_source(source: str, *, filename: str = "<string>") -> RunResult:
+    """Run God Code source from a host program and capture the outcome.
+
+    REVEAL output is captured per-interpreter (via the interpreter's ``emit``
+    hook), so this is safe to call many times in one process.  Plugin
+    auto-loading still applies unless ``GODCODE_NO_PLUGINS=1`` is set.
+    Embedding runs do not write the audit log.
+    """
+    from godcode.errors import GodCodeError, ReturnSignal
+    from godcode.interpreter import Interpreter
+
+    lines: list[str] = []
+    interpreter = Interpreter(log_path=None)
+    interpreter.emit = lines.append
+    try:
+        interpreter.run_source(source, source_name=filename)
+    except ReturnSignal as ret:
+        # A top-level RETURN becomes the run's return value.
+        return RunResult(
+            output="\n".join(lines), return_value=ret.value, error=None, ok=True
+        )
+    except GodCodeError as err:
+        return RunResult(
+            output="\n".join(lines),
+            return_value=None,
+            error=str(err),
+            ok=False,
+        )
+    except Exception as exc:  # a host/plugin failure outside the divine errors
+        return RunResult(
+            output="\n".join(lines),
+            return_value=None,
+            error=f"the outer world faltered: {exc!r}",
+            ok=False,
+        )
+    return RunResult(
+        output="\n".join(lines),
+        return_value=interpreter.last_value,
+        error=None,
+        ok=True,
+    )
+
+
+def run_file(path: str | Path) -> RunResult:
+    """Run a God Code scroll file from a host program; see :func:`run_source`."""
+    try:
+        source = Path(path).read_text(encoding="utf-8")
+    except OSError as exc:
+        return RunResult(
+            output="",
+            return_value=None,
+            error=f"cannot read '{path}': {exc.strerror or exc}",
+            ok=False,
+        )
+    return run_source(source, filename=str(path))
+
+
+__all__ = ["__version__", "RunResult", "run_source", "run_file"]

godcode/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m godcode <subcommand>``."""
+import sys
+
+from godcode.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

godcode/agentics.py

@@ -0,0 +1,235 @@
+"""Machine-readable output for AI agents (Mini-Pillar 5 — Agentics).
+
+This module turns God Code diagnostics and run results into stable JSON
+payloads an agent can parse without scraping divine prose. The CLI wires
+it in behind ``--json`` on the ``run`` and ``check`` commands.
+
+Error-code mapping choice
+-------------------------
+Codes are a small, stable, language-agnostic vocabulary derived from the
+v2.0 exception hierarchy in :mod:`godcode.errors` (there is no
+``GodCodeSyntaxError`` class in v2.0, so the mapping below is explicit):
+
+    LexerError       -> LEXER_ERROR
+    ParseError       -> PARSE_ERROR
+    GodRuntimeError  -> RUNTIME_ERROR
+
+Any other ``GodCodeError`` subclass falls back to a mechanical
+CamelCase -> UPPER_SNAKE conversion of its class name
+(e.g. ``FooBarError`` -> ``FOO_BAR_ERROR``). Failures that are not God
+Code failures at all (an unreadable scroll file) use ``FILE_ERROR``,
+which is not an exception class.
+
+Capture choice
+--------------
+``run`` output is captured with :func:`contextlib.redirect_stdout` into
+a :class:`io.StringIO` around the interpreter call — no dependency on
+any capture hooks from sibling pillars.
+
+Seals
+-----
+After the run we diff the interpreter's bound ``ledger`` (when present)
+against its block count before the run. Blocks sealed during the run are
+reported as ``{"block": <index>, "hash": <sha>}``. When no ledger is
+bound or it cannot be read, ``seals`` is ``[]`` — never an error.
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+TOOL_NAME = "godcode"
+
+# ---------------------------------------------------------------------------
+# error codes
+# ---------------------------------------------------------------------------
+_CODE_MAP = {
+    "LexerError": "LEXER_ERROR",
+    "ParseError": "PARSE_ERROR",
+    "GodRuntimeError": "RUNTIME_ERROR",
+}
+
+_HINTS = {
+    "LEXER_ERROR": (
+        "Scan the reported line for stray symbols or an unterminated "
+        "string; God Code strings use double quotes."
+    ),
+    "PARSE_ERROR": (
+        "Every scroll needs BEGIN CREATION ... END CREATION; comparisons "
+        "use IS / IS NOT, and every block needs its closer "
+        "(ENDIF, ENDFOR, ENDWHILE, END RITE)."
+    ),
+    "RUNTIME_ERROR": (
+        "The scroll parsed but stumbled while running — DECLARE every "
+        "name before use and re-read the reported line."
+    ),
+    "FILE_ERROR": "Check the path — the scroll must exist and be readable.",
+}
+
+
+def _to_snake(name: str) -> str:
+    return re.sub(r"(?<!^)(?=[A-Z])", "_", name).upper()
+
+
+def error_code(err) -> str:
+    """Map a God Code exception to its stable machine code."""
+    name = type(err).__name__
+    if name in _CODE_MAP:
+        return _CODE_MAP[name]
+    snake = _to_snake(name)
+    return snake if snake.endswith("_ERROR") else snake + "_ERROR"
+
+
+def hint_for(code: str) -> str | None:
+    """One-line actionable suggestion for a code, or None."""
+    return _HINTS.get(code)
+
+
+def diagnostic(err, *, severity: str = "error") -> dict:
+    """Turn a GodCodeError into a JSON-serializable diagnostic dict."""
+    code = error_code(err)
+    # err.msg is the clean message; str(err) may append "(line N)" which
+    # would duplicate the structured line/col fields below.
+    return {
+        "line": getattr(err, "line", None),
+        "col": getattr(err, "col", None),
+        "code": code,
+        "severity": severity,
+        "message": getattr(err, "msg", None) or str(err),
+        "hint": hint_for(code),
+    }
+
+
+def _file_error_diagnostic(path: str, exc: OSError) -> dict:
+    detail = exc.strerror or str(exc)
+    return {
+        "line": None,
+        "col": None,
+        "code": "FILE_ERROR",
+        "severity": "error",
+        "message": f"godcode: cannot read '{path}': {detail}",
+        "hint": hint_for("FILE_ERROR"),
+    }
+
+
+# ---------------------------------------------------------------------------
+# payload builders
+# ---------------------------------------------------------------------------
+def check_payload(file: str, ok: bool, diagnostics: list[dict]) -> dict:
+    return {
+        "tool": TOOL_NAME,
+        "command": "check",
+        "file": file,
+        "ok": ok,
+        "diagnostics": diagnostics,
+    }
+
+
+def run_payload(file: str, ok: bool, output: list[str],
+                seals: list[dict], error: dict | None, ms: int,
+                intents: list[dict] | None = None) -> dict:
+    return {
+        "tool": TOOL_NAME,
+        "command": "run",
+        "file": file,
+        "ok": ok,
+        "output": output,
+        "seals": seals,
+        "intents": intents if intents is not None else [],
+        "error": error,
+        "stats": {"ms": ms},
+    }
+
+
+def emit(payload: dict) -> None:
+    """Write one JSON document to stdout; nothing else may be printed."""
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
+    sys.stdout.flush()
+
+
+# ---------------------------------------------------------------------------
+# --json command implementations (called from godcode.cli)
+# ---------------------------------------------------------------------------
+def cmd_check_json(args) -> int:
+    """`godcode check --json FILE`. Exit 0 if pure, 1 if diagnostics."""
+    from godcode.errors import GodCodeError
+    from godcode.lexer import Lexer
+    from godcode.parser import Parser
+
+    try:
+        source = Path(args.file).read_text(encoding="utf-8")
+    except OSError as exc:
+        emit(check_payload(args.file, False, [_file_error_diagnostic(args.file, exc)]))
+        return 1
+    try:
+        Parser(Lexer(source).lex()).parse()
+    except GodCodeError as err:
+        emit(check_payload(args.file, False, [diagnostic(err)]))
+        return 1
+    emit(check_payload(args.file, True, []))
+    return 0
+
+
+def _ledger_block_count(interp) -> int | None:
+    ledger = getattr(interp, "ledger", None)
+    if ledger is None:
+        return None
+    try:
+        return len(ledger.read_all())
+    except Exception:
+        return None
+
+
+def _new_seals(interp, before: int | None) -> list[dict]:
+    """Best-effort list of covenant blocks sealed during the run."""
+    if before is None:
+        return []
+    ledger = getattr(interp, "ledger", None)
+    if ledger is None:
+        return []
+    try:
+        blocks = ledger.read_all()[before:]
+    except Exception:
+        return []
+    seals = []
+    for block in blocks:
+        if isinstance(block, dict) and "hash" in block:
+            seals.append({"block": block.get("index"), "hash": block.get("hash")})
+    return seals
+
+
+def cmd_run_json(args) -> int:
+    """`godcode run --json FILE`. Exit 0 on success, 1 on failure."""
+    from godcode.errors import GodCodeError
+    from godcode.cli import _make_interpreter  # shared with the plain run path
+
+    try:
+        source = Path(args.file).read_text(encoding="utf-8")
+    except OSError as exc:
+        emit(run_payload(args.file, False, [], [], _file_error_diagnostic(args.file, exc), 0))
+        return 1
+
+    interp = _make_interpreter(args.log)
+    seals_before = _ledger_block_count(interp)
+
+    buf = io.StringIO()
+    error: dict | None = None
+    start = time.perf_counter()
+    with contextlib.redirect_stdout(buf):
+        try:
+            interp.run_source(source, source_name=args.file)
+        except GodCodeError as err:
+            error = diagnostic(err)
+    ms = int((time.perf_counter() - start) * 1000)
+
+    output = buf.getvalue().splitlines()
+    seals = _new_seals(interp, seals_before)
+    intents = list(getattr(interp, "intent_checks", []) or [])
+    emit(run_payload(args.file, error is None, output, seals, error, ms,
+                     intents=intents))
+    return 0 if error is None else 1

godcode/ast.py

@@ -0,0 +1,227 @@
+"""Abstract syntax tree nodes for God Code v2.0.
+
+Every node carries 1-based ``line``/``col`` of the token that opened it.
+Expression fields are annotated with the ``Expr`` alias (a union of all
+expression node types).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Union
+
+# Filled in below once the classes exist; string form keeps runtime cheap.
+Expr = Union[
+    "BinaryOp", "UnaryOp", "Literal", "Identifier",
+    "ListLiteral", "Index", "CallExpr",
+]
+
+
+# -- program structure -------------------------------------------------------
+
+@dataclass
+class Program:
+    statements: list = field(default_factory=list)
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class CreationBlock:
+    statements: list = field(default_factory=list)
+    line: int = 1
+    col: int = 1
+
+
+# -- statements --------------------------------------------------------------
+
+@dataclass
+class Declare:
+    name: str
+    value: Expr
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class DeclareIntent:
+    """DECLARE INTENT "words..." ON rite_name -- the v4.0 intent layer."""
+    text: str
+    rite: str
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Breathe:
+    name: str
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Reveal:
+    expr: Expr
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Prophesy:
+    text: str
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Ascend:
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Reflect:
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Bless:
+    name: str
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Anoint:
+    name: str
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class SealStmt:
+    expr: Expr
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Testify:
+    expr: Expr
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class IfStmt:
+    cond: Expr
+    then_body: list = field(default_factory=list)
+    else_body: list = field(default_factory=list)
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class ForLoop:
+    var: str
+    iterable: Expr
+    body: list = field(default_factory=list)
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class WhileLoop:
+    cond: Expr
+    body: list = field(default_factory=list)
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class DefineRite:
+    name: str
+    params: list = field(default_factory=list)  # list[str]
+    body: list = field(default_factory=list)
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Return:
+    expr: Expr | None = None
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Import:
+    path: str
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class ExprStmt:
+    expr: Expr
+    line: int = 1
+    col: int = 1
+
+
+# -- expressions -------------------------------------------------------------
+
+@dataclass
+class BinaryOp:
+    # op: '+','-','*','/','%', '==','!=','<','>','<=','>=', 'and','or'
+    op: str
+    left: Expr
+    right: Expr
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class UnaryOp:
+    # op: 'not', '-'
+    op: str
+    operand: Expr
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Literal:
+    value: object  # int | float | str | bool | None
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Identifier:
+    name: str
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class ListLiteral:
+    items: list = field(default_factory=list)  # list[Expr]
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class Index:
+    obj: Expr
+    index: Expr
+    line: int = 1
+    col: int = 1
+
+
+@dataclass
+class CallExpr:
+    callee: str
+    args: list = field(default_factory=list)  # list[Expr]
+    line: int = 1
+    col: int = 1