codecalc 0.1.0__py3-none-win_amd64.whl

codecalc/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: codecalc
+description: Use when about to state a number, claim two programs are equivalent, claim a speedup, or state a complexity — codecalc computes these exactly instead of estimating them, and this file says when calling is mandatory and how results must be reported.
+---
+
+# codecalc
+
+You are a language model. You are good at writing code and bad at arithmetic,
+and the failure is not that you are unsure — it is that you are confident. This
+file exists because "call a tool when you are uncertain" is worthless advice to
+a model that feels certain about `0.1 + 0.2`.
+
+So the rules below key on the SITUATION, never on how sure you feel.
+
+## Call these — mandatory, no exceptions
+
+Not a preference. If the situation matches, the call happens before you write
+the number.
+
+| Situation | Tool |
+|---|---|
+| Any **non-integer** operand or result | `calc_exact` |
+| Any **comparison** whose verdict you will state | `compare_threshold` |
+| Integers past **2^53** (9007199254740992) | `calc_exact`, and `float_repr` if a float is involved |
+| Percentages, ratios, shares | `percentage` |
+| Unit, byte, duration or epoch conversion | `convert_units`, `data_sizes`, `human_duration`, `epoch_time` |
+| Any number that appears in your answer **as a claim** rather than an illustration | whichever of the above fits |
+| You ported code A → B and are about to call it a port | `verify_translation` |
+| You are about to state that a rewrite is **faster** | `verify_optimization` |
+| You are about to say two languages **behave the same** | `compare_edge_cases` |
+| You are about to state a **Big-O** | `analyze_complexity` (inferred) or `benchmark` (measured) — and say which |
+
+**2^53 is not academic.** `float_repr(9007199254740993)` reports
+`stored: "9007199254740992"`. The value changed and nothing raised. That is the
+boundary, and `int_widths` will not show it to you — that tool reports machine
+integer widths (i8…u64), which is a different question.
+
+## Do not call these — no justification needed
+
+Calling a tool for these is noise, and a rule that fires constantly is a rule
+someone turns off:
+
+- small-integer intermediate arithmetic — `2 + 3 + 4` needs no tool
+- order-of-magnitude estimates you label as estimates
+- arithmetic inside prose that nobody will act on
+- `execute_code` to confirm syntax you can read
+
+Operand count is **not** the test. `0.1 + 0.2` has two operands and is the
+canonical failure; `2 + 3 + 4` has three and is never wrong. Type predicts
+error. Length does not.
+
+## Report what came back — mandatory, no exceptions
+
+This is the second-order failure: call the tool correctly, then misreport it.
+Every field below exists because the result would otherwise imply something
+untrue, and each was added after that implication bit someone.
+
+| Field | What you must say |
+|---|---|
+| `passed: true` | State `total`. "Equivalent on 7 inputs" — never "verified equivalent" |
+| `inconclusive > 0` | Surface it. Not a pass, not a failure, and the caller is entitled to know which they got |
+| `unenforced: [...]` non-empty | The guarantee you are about to describe **did not hold**. Name what was not applied |
+| `backend: "python"` | Weaker sandbox. `no_net` was not applied and `peak_memory_kb` is `None` |
+| `analysis: "regex-fallback"` | The structure was **guessed**, not parsed |
+| `method: "static-estimate"` | Nobody measured this. `benchmark` reports `method: "empirical"` |
+| `output_error` present | `stdout`/`stderr` are **not** what the program produced |
+| `ok: false` | Say what failed. The `error` field is written to be quoted |
+
+**Never drop a field you do not understand. Quote it.**
+
+That rule is not for careless models. In one session an agent verifying this
+very codebase — carefully, with the source open — made three probe errors in a
+row: reversed arguments that made a nested loop report `O(1)`, a read of a
+`divergences` key that does not exist (it is `mismatched`), and the same
+wrong-key mistake on `algebraic_equiv` (it is `identical`). Each was caught only
+by printing the whole result instead of the field it expected. Confidence about
+a result's shape is exactly as unreliable as confidence about arithmetic.
+
+## What this tool set will not do for you
+
+- It does not check that a package or function **exists**. A fabricated API is
+  still your error; `execute_code` with an import is the closest available check.
+- `verify_translation` proves equivalence **on the inputs it ran**, which are
+  `DEFAULT_EDGE_INPUTS` unless you pass your own. It is evidence, not proof.
+  Pass inputs that would distinguish your port if it were wrong.
+- `analyze_complexity` reads structure. It cannot see work hidden inside a
+  library call.

codecalc/__init__.py

@@ -0,0 +1,3 @@
+"""codecalc — universal code & logic calculator for AI models."""
+
+__version__ = "0.1.0"

codecalc/__main__.py

@@ -0,0 +1,19 @@
+"""`python -m codecalc` — the same entry point as the `codecalc` script.
+
+`[project.scripts]` already gives `codecalc` a console script pointing at
+`server:main`, so `uvx codecalc` and `pipx run codecalc` have always worked.
+What did not work was `python -m codecalc`, which needs this file and failed
+with "No module named codecalc.__main__" — the form people reach for when a
+package is installed but its script directory is not on PATH, which is the
+normal state inside a venv someone has not activated.
+
+Deliberately thin. Anything that lives here is invisible to the console-script
+path and would be a second way for the two to diverge.
+"""
+
+from __future__ import annotations
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

codecalc/_worker_bootstrap.py

@@ -0,0 +1,211 @@
+"""Stateful python3 REPL worker: JSON-lines request/response over a channel
+executed code cannot reach.
+
+Three things here are deliberate and were all bugs before.
+
+**The protocol does not share a file descriptor with the executed code.** The
+first version swapped `sys.stdout` for a StringIO and wrote responses with
+`print()`. That is a Python-level rebind: a subprocess inherits **fd 1** and
+writes straight past it. So an entirely ordinary session line —
+
+    subprocess.run(["echo", "hi"])
+
+— put raw bytes into the response stream. At startup fd 1 is duplicated to a
+private descriptor that only this module writes to, and fd 1/2 are then pointed
+at capture files. Nothing the executed code can do reaches the protocol channel,
+and as a bonus subprocess output is now CAPTURED rather than lost.
+
+**On Windows, the fd-1 dup above is not trusted, and a file stands in for it.**
+`os.dup2` remaps this process's CRT file-descriptor table, but a subprocess
+started by executed code without an explicit stdout override can still be
+handed the OS-level standard HANDLE instead — a separate piece of state the
+CRT does not reliably keep in sync with the fd table on Windows. When
+`CODECALC_PROTO_PATH` is set (Windows, or `_FORCE_FILE_PROTOCOL` in
+sessions.py forcing the same route on POSIX for test coverage), responses are
+appended to that file instead of written to the fd-1 dup, exactly mirroring
+the node worker's Windows route (`sessions.py`'s `_TailReader`). The per-call
+fds are additionally mirrored onto the OS-level standard handles there (see
+`_set_std_handle` below), so a child that queries the raw handle rather than
+the CRT fd still lands in the capture file, not wherever fd 1 used to point.
+
+**Every response carries the id of the request it answers.** Corruption used to
+be unrecoverable *and silent*: the reader consumed the junk, left the real reply
+queued, and every later call returned the PREVIOUS call's result with
+`ok: True`. Measured — a call asking for `marker-4` came back with the output of
+the call before it. An echoed id makes a desync detectable instead of trusted;
+see `Worker.run`, which kills the worker rather than return a stale answer.
+
+Output is capped here too. The sandboxed path caps at 64 KiB and reports OLE;
+this path returned a 20 MB string whole, built three times over in memory on the
+way out through JSON.
+"""
+
+import contextlib
+import io
+import json
+import os
+import sys
+import tempfile
+import traceback
+from pathlib import Path
+
+#: Matches MAX_OUTPUT_BYTES in the Rust executor. A session is not exempt from
+#: the output cap just because it is stateful.
+MAX_OUTPUT_BYTES = 64 * 1024
+
+# The protocol channel. Two routes:
+#
+#   CODECALC_PROTO_PATH set    responses are appended to that file. Set on
+#                               Windows (and by sessions.py's
+#                               _FORCE_FILE_PROTOCOL, on POSIX, for test
+#                               coverage) because the fd-1 dup below is not
+#                               trustworthy there.
+#   unset (default, POSIX)     a dup of the ORIGINAL stdout, taken before
+#                               anything is redirected. Executed code cannot
+#                               name this descriptor, and closing fd 1 (which
+#                               code is free to do) does not touch it.
+_proto_path = os.environ.get("CODECALC_PROTO_PATH", "")
+_proto_path_obj = Path(_proto_path) if _proto_path else None
+if _proto_path:
+    _proto = None
+else:
+    _proto_fd = os.dup(1)
+    _proto = os.fdopen(_proto_fd, "w", encoding="utf-8", newline="\n")
+
+
+def _write_proto(line: str) -> None:
+    if _proto_path_obj is not None:
+        # Append, not write: a fresh open() per response so the file descriptor
+        # itself is never held across the exec() below, where executed code
+        # could otherwise inherit or close it.
+        with _proto_path_obj.open("a", encoding="utf-8", newline="\n") as fh:
+            fh.write(line)
+    else:
+        _proto.write(line)
+        _proto.flush()
+
+
+# On Windows, mirror the per-call fd 1/2 redirection onto the OS-level
+# standard handles too. `os.dup2` only remaps this process's CRT
+# file-descriptor table; a child spawned by executed code without an explicit
+# stdout override can still be handed GetStdHandle()'s value instead, which
+# the CRT does not reliably keep pointed at the same place. Elsewhere this is
+# a no-op: the fd-1 dup2 is already sufficient on POSIX.
+_STD_OUTPUT_HANDLE = -11
+_STD_ERROR_HANDLE = -12
+
+if os.name == "nt":
+    import ctypes
+    import msvcrt
+
+    _kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+
+    def _set_std_handle(std_id: int, fd: int) -> int:
+        """Point the OS-level standard handle at fd's handle; return the old one."""
+        prev = _kernel32.GetStdHandle(std_id)
+        _kernel32.SetStdHandle(std_id, msvcrt.get_osfhandle(fd))
+        return prev
+
+    def _restore_std_handle(std_id: int, handle: int) -> None:
+        _kernel32.SetStdHandle(std_id, handle)
+else:
+    def _set_std_handle(std_id: int, fd: int) -> int:
+        return -1
+
+    def _restore_std_handle(std_id: int, handle: int) -> None:
+        pass
+
+
+# Requests still arrive on stdin. The iterator below binds to this object once,
+# so rebinding sys.stdin per call cannot disturb it.
+_requests = sys.stdin
+
+ns = {"__name__": "__main__", "__builtins__": __builtins__}
+
+
+def _read_capped(fh) -> tuple[str, bool]:
+    """Read a capture file, capped, reporting whether anything was dropped."""
+    fh.seek(0)
+    data = fh.read(MAX_OUTPUT_BYTES + 1)
+    truncated = len(data) > MAX_OUTPUT_BYTES
+    if truncated:
+        data = data[:MAX_OUTPUT_BYTES]
+    return data.decode("utf-8", errors="replace") + ("\n...[truncated]" if truncated else ""), truncated
+
+
+def _respond(payload: dict) -> None:
+    _write_proto(json.dumps(payload) + "\n")
+
+
+for _line in _requests:
+    _line = _line.strip()
+    if not _line:
+        continue
+    try:
+        req = json.loads(_line)
+    except Exception:
+        continue
+    code = req.get("code", "")
+    stdin_data = req.get("stdin", "")
+    req_id = req.get("id")
+
+    # Not a `with` block: these files have to outlive the try/finally that
+    # restores fds 1 and 2, and they are read after the restore. Closed
+    # explicitly below.
+    out_f = tempfile.TemporaryFile()  # noqa: SIM115
+    err_f = tempfile.TemporaryFile()  # noqa: SIM115
+    # Save fds 1/2 so they can be restored even if the executed code closes them.
+    saved_out, saved_err = os.dup(1), os.dup(2)
+    prev_stdin, prev_stdout, prev_stderr = sys.stdin, sys.stdout, sys.stderr
+    saved_std_out_handle = saved_std_err_handle = None
+    try:
+        os.dup2(out_f.fileno(), 1)
+        os.dup2(err_f.fileno(), 2)
+        # See the module docstring: on Windows the CRT fd redirection above
+        # does not, by itself, reach a child spawned without an explicit
+        # stdout/stderr override. Mirroring it onto the OS-level standard
+        # handles is what makes THAT child land in the capture files too.
+        saved_std_out_handle = _set_std_handle(_STD_OUTPUT_HANDLE, 1)
+        saved_std_err_handle = _set_std_handle(_STD_ERROR_HANDLE, 2)
+        # Python-level streams over the SAME descriptors, so interpreter output
+        # and subprocess output interleave in the order they were written.
+        sys.stdout = io.TextIOWrapper(os.fdopen(os.dup(1), "wb"), encoding="utf-8",
+                                      errors="replace", write_through=True)
+        sys.stderr = io.TextIOWrapper(os.fdopen(os.dup(2), "wb"), encoding="utf-8",
+                                      errors="replace", write_through=True)
+        sys.stdin = io.StringIO(stdin_data)
+        with contextlib.redirect_stdout(sys.stdout), contextlib.redirect_stderr(sys.stderr):
+            exec(compile(code, "<session>", "exec"), ns)
+        ok, err = True, ""
+    except BaseException:
+        # BaseException, not Exception: sys.exit() in a session line must end
+        # that line, not the worker.
+        ok, err = False, traceback.format_exc()
+    finally:
+        for stream in (sys.stdout, sys.stderr):
+            with contextlib.suppress(Exception):
+                stream.flush()
+        if saved_std_out_handle is not None:
+            _restore_std_handle(_STD_OUTPUT_HANDLE, saved_std_out_handle)
+        if saved_std_err_handle is not None:
+            _restore_std_handle(_STD_ERROR_HANDLE, saved_std_err_handle)
+        os.dup2(saved_out, 1)
+        os.dup2(saved_err, 2)
+        os.close(saved_out)
+        os.close(saved_err)
+        sys.stdin, sys.stdout, sys.stderr = prev_stdin, prev_stdout, prev_stderr
+
+    stdout_s, out_trunc = _read_capped(out_f)
+    stderr_s, err_trunc = _read_capped(err_f)
+    out_f.close()
+    err_f.close()
+
+    _respond({
+        "id": req_id,
+        "ok": ok,
+        "stdout": stdout_s,
+        "stderr": stderr_s or err,
+        "exit_code": 0 if ok else 1,
+        "output_truncated": out_trunc or err_trunc,
+        "verdict": "OLE" if (out_trunc or err_trunc) else ("OK" if ok else "RTE"),
+    })

codecalc/complexity.py

@@ -0,0 +1,162 @@
+"""Complexity analyzer: static heuristic Big-O estimation.
+
+Language-agnostic structural scan:
+  - loop constructs per nesting depth  -> O(n^k) base
+  - recursion detection                -> exponential / nlogn flags
+  - linear-scan builtins (sort etc.)   -> n log n adjustments
+  - hash/constant-time ops             -> n^1 stays n
+
+Structural only: a tree-sitter parse plus growth heuristics. There is no LLM
+in this path and no network call. An optional LLM "second opinion" used to sit
+behind CODECALC_COMPLEXITY_LLM; it is gone, because a static analyser that can
+make a network call is a different kind of tool, and the deterministic estimate
+was always the product.
+"""
+
+from __future__ import annotations
+
+import re
+
+from . import parsing
+
+LOOP_RE = re.compile(
+    r"\b(for|while|foreach|until|loop|repeat)\b"
+    r"|\bfor\s*\("          # C-style for(
+    r"|\.forEach\(|\.map\(|\.filter\(|\.reduce\("   # JS iterators
+    r"|for\s+\w+\s+in\b"    # python/ruby for x in
+    r"|for\s+\w+\s*:="      # go for x :=
+    r"|for\s+\w+\s+of\b"    # JS for x of
+)
+RECURSION_RE = re.compile(
+    r"\b(def|func(?:tion)?|fn|sub)\s+(\w+)\s*\("
+    r"|public\s+(?:static\s+)?\w+\s+(\w+)\s*\("
+)
+CALL_RE = re.compile(r"\b(\w+)\s*\(")
+SORT_RE = re.compile(r"\.sort\(|\.sort_by\(|\bsort\(|\bsorted\(|\bsort_by\b")
+BINARY_RE = re.compile(r"\bbinary_search|bisect|\bmid\s*=\s*\(|while\s+\w+\s*<=\s*\w+.*(?:mid|lo|hi)")
+HASH_RE = re.compile(r"\bdict\b|\bHashMap\b|\bMap\b|\bHashSet\b|\bSet\b|\b{}|\bHash\b")
+NESTED_RE = re.compile(r"^\s+")   # indentation marker
+
+
+def _count_loops(code: str) -> tuple[int, int]:
+    """Returns (loop_count, max_nesting_depth) via indentation-aware scan."""
+    lines = code.splitlines()
+    indent_stack: list[int] = []
+    loops = 0
+    max_depth = 0
+    for raw in lines:
+        if not raw.strip() or raw.strip().startswith(("#", "//", "/*", "*")):
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        while indent_stack and indent <= indent_stack[-1]:
+            indent_stack.pop()
+        if LOOP_RE.search(raw) and not raw.strip().startswith(("}", ")")):
+            loops += 1
+            indent_stack.append(indent)
+            max_depth = max(max_depth, len(indent_stack))
+    return loops, max_depth
+
+
+def _detect_recursion(code: str) -> tuple[bool, str]:
+    """Best-effort recursion detection: does any function call itself?"""
+    funcs = []
+    for m in RECURSION_RE.finditer(code):
+        name = m.group(2) or m.group(3)
+        if name:
+            funcs.append(name)
+    for fn in funcs:
+        # find the function body and look for self-calls
+        m = re.search(rf"\b{fn}\s*\([^)]*\)[^#\n]*\n((?:.|\n)*?)(?=\n\S|\Z)", code)
+        if m and re.search(rf"\b{fn}\s*\(", m.group(1)):
+            return True, fn
+    return False, ""
+
+
+def analyze(code: str, language: str = "python3") -> dict:
+    """Estimate asymptotic complexity from the code's STRUCTURE.
+
+    Loop counting and recursion detection come from a real parser
+    (`codecalc.parsing`). They used to come from regexes, which counted the word
+    "for" inside strings, comments and identifiers like `format()`, read a
+    chained `.map().filter().reduce()` as three loops, and called a docstring
+    mentioning a function's own name "recursion". tests/test_parsing_vs_regex.py
+    holds the divergent cases with the correct answer for each.
+
+    `analysis` in the result says which path produced the numbers, so a caller
+    can tell a parse from a fallback instead of assuming.
+    """
+    facts = parsing.analyse(code, language)
+    if facts.parsed:
+        loops, depth = facts.loops, facts.max_loop_depth
+        recursive = bool(facts.recursive_functions)
+        fn = facts.recursive_functions[0] if recursive else ""
+        analysis = "tree-sitter"
+    else:
+        # No grammar for this language, or the parser rejected the input. Say so
+        # rather than reporting a heuristic as though it were a parse.
+        loops, depth = _count_loops(code)
+        recursive, fn = _detect_recursion(code)
+        analysis = "regex-fallback"
+
+    # These two stay textual: "does this call a sort" and "does this use a hash
+    # map" are library questions, not grammar ones, and a parser has no more
+    # authority over them than a regex does.
+    has_sort = bool(SORT_RE.search(code))
+    has_hash = bool(HASH_RE.search(code))
+
+    # base estimate
+    if recursive:
+        estimate = "O(2^n) — recursion detected"
+        basis = f"recursive function '{fn}'"
+    elif depth >= 2:
+        estimate = f"O(n^{depth})"
+        basis = f"{depth} nested loop levels ({loops} loop constructs)"
+    elif loops == 1:
+        estimate = "O(n) — with sort: O(n log n)"
+        basis = "1 loop level"
+    elif has_sort and loops == 0:
+        estimate = "O(n log n)"
+        basis = "sorting call, no loops"
+    else:
+        estimate = "O(1)"
+        basis = "no loops, no recursion"
+
+    notes = []
+    if has_sort:
+        notes.append("sort/builtin detected (O(n log n) worst case)")
+    if has_hash:
+        notes.append("hash structures → average-case O(1) lookups")
+    if loops == 0 and not recursive and not has_sort:
+        notes.append("constant-time surface; may hide loops in library calls")
+
+    if analysis == "regex-fallback" and facts.reason:
+        notes.append(f"structural heuristic only ({facts.reason})")
+    if facts.parsed and facts.has_error:
+        notes.append("source has syntax errors; the parse is partial")
+
+    result = {
+        "ok": True,
+        "estimate": estimate,
+        "basis": basis,
+        "loops": loops,
+        "max_nesting": depth,
+        "recursion": recursive,
+        # TWO ORTHOGONAL FACTS, and only one of them was reported before.
+        # `analysis` says how the source was READ — parsed by tree-sitter, or
+        # guessed by regex when no grammar was available. `method` says whether
+        # the answer was MEASURED at all, and it never was: this counts loops
+        # and detects recursion. A caller could previously see
+        # analysis="tree-sitter" and reasonably hear "we determined the
+        # complexity", when the truth is "we read the structure accurately and
+        # inferred from it". `benchmark` is the empirical counterpart and
+        # reports method="empirical".
+        "method": "static-estimate",
+        "analysis": analysis,
+        "grammar": facts.grammar,
+        "functions": facts.functions if facts.parsed else [],
+        "notes": notes,
+    }
+
+    return result
+
+