morvix 0.1.0__tar.gz

morvix-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.9", "3.12"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: "21"
+      # valgrind is Linux-only; install it so the memory-correctness test runs
+      # for real rather than skipping. gcc/g++ and rustc are preinstalled on the
+      # GitHub runners, so the C/C++/Rust adapter tests run too.
+      - name: Install valgrind (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y valgrind
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  # The sacred path: prove a Receiver can run a package with ONLY system
+  # python3 - no Morvix install anywhere. One job builds a package; a second,
+  # deliberately Morvix-free, job unpacks it and runs ./run.sh.
+  build-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e .
+      - name: Build a shareable package
+        run: |
+          mkdir demo && cd demo
+          printf 'import sys\nprint(sum(int(x) for x in sys.stdin.read().split()))\n' > sol.py
+          morvix init --name demo --language python
+          morvix import sol.py
+          morvix reference sol.py
+          morvix gen --random --shape ints --count 5 --seed 1
+          morvix gen --expected
+          morvix package --zip --out ../pkg.zip
+          cp sol.py ../sol.py
+      - uses: actions/upload-artifact@v7
+        with:
+          name: receiver-package
+          path: |
+            pkg.zip
+            sol.py
+
+  receiver-clean:
+    needs: build-package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v8
+        with:
+          name: receiver-package
+      # No checkout, no pip install: Morvix must not be present on this runner.
+      - name: Confirm Morvix is absent
+        run: |
+          if python3 -c "import morvix" 2>/dev/null; then
+            echo "morvix is importable here - this job must be Morvix-free"; exit 1
+          fi
+          echo "morvix is absent - good"
+      - name: Unpack and run ./run.sh with only system python3
+        run: |
+          mkdir r && cd r
+          unzip ../pkg.zip
+          cp ../sol.py .
+          sh run.sh sol.py | tee out.txt
+          grep -q "passed" out.txt

morvix-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,38 @@
+name: Publish to PyPI
+
+# Publishes to PyPI when you create a GitHub Release. Uses PyPI Trusted
+# Publishing (OIDC) - no API token is stored anywhere. The build and the
+# upload are split so the upload job is the only one with id-token permission.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:        # lets you trigger a publish by hand too
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # must match the environment set on PyPI's publisher
+    permissions:
+      id-token: write          # required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

morvix-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+
+# Local scratch / sandboxes used while testing morvix by hand
+/scratch/
+/sandbox/

morvix-0.1.0/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Morvix is a Python CLI that lets a student build test cases from their own solution, run their code
+against them, and package the harness to share with classmates. The full design lives in
+`documentation.md` (831 lines) - read the relevant section before changing behavior; the code is
+organized to mirror it and many comments cite section numbers (e.g. "Section 14.6").
+
+## Dev commands
+
+```sh
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"   # set up
+.venv/bin/morvix                 # interactive shell
+.venv/bin/morvix <cmd> ...       # one-shot (same verbs as the shell)
+.venv/bin/python -m compileall -q morvix   # quick syntax check of everything
+.venv/bin/pytest                 # run the test suite
+.venv/bin/pytest tests/test_x.py::test_y   # a single test
+```
+
+The toolchains used by the language adapters (`gcc`/`g++`, `nasm`, `javac`/`java`, `rustc`,
+`valgrind`) must be on PATH to exercise those paths. `rustc` and `valgrind` are commonly absent on
+macOS; those features degrade with an honest warning rather than faking results.
+
+## The architecture that matters
+
+Everything hangs on **three orthogonal axes that never multiply against each other** (Section 4.1).
+When adding capability, add to exactly one axis:
+
+- **Language adapter** (`morvix/adapters/<lang>.py`) - turns source into something runnable. Knows
+  nothing about tests. Subclass `Adapter`, implement `build/run_spec/describe`, call `register()`.
+- **Execution model** (`morvix/models.py` for `stdio`; `morvix/execmodels/<name>.py` for the rest) -
+  how a runnable thing is driven and what its observable output is. A function
+  `(case, env, limits) -> Observation` registered with `register_model`.
+- **Comparison strategy** (`morvix/compare.py` for exact/whitespace; `morvix/comparators.py` for
+  float/hash/checker) - given output + expected, decide pass/fail. A function
+  `(CompareInput) -> Verdict` registered with `register_comparator`.
+
+`morvix/judge.py` is the engine that ties them together: build once, run each case through the
+model, then combine the enabled dimensions (output match + expected exit/signal + memory) so a case
+can require all of them at once (Section 14.7). `morvix/process.py` is the bottom layer (spawn,
+rlimits, timing, `wait4`-based per-child memory, `LC_ALL=C` locale) and is the single place that
+papers over Linux/macOS differences.
+
+The stack, top to bottom: shell/CLI (`app`, `shell`, `registry`) -> shared components
+(`components/`) -> commands (`commands/`) -> orchestration (`project`, `generators`, `manifest`,
+`packaging`, `workflow`, `results`) -> the three axes -> `process`.
+
+## Key conventions and invariants
+
+- **Two entry points, one vocabulary.** `morvix/registry.py` builds one argparse parser used by both
+  the REPL and one-shot mode. Each command module exposes `NAME`, `configure(parser)`,
+  `run(ctx, args) -> int`, and an optional `complete(ctx, prev_words, word)`. Errors raise (they do
+  not `sys.exit`) so the shell survives them.
+- **One shared UI layer.** Commands never hand-roll a menu, prompt, table, or message. They compose
+  from `morvix/components/` (selection, choice, form, confirm, table, progress) and print only via
+  `ctx.messenger`. Each component has a non-interactive fallback driven by `ctx.interactive`.
+- **The directory is the state.** No database. `config/project.json` + `config/cases.json` +
+  `config/runners/*.json` are the editable truth; `morvix.json` is the generated, shareable manifest
+  regenerated on every `ctx.save_project()`. Config is JSON throughout.
+- **The runner core is sacred and standalone.** `morvix/runner_core/morvix_runner.py` ships verbatim
+  inside packages, must import **nothing** from `morvix`, must be **stdlib-only**, and must run on a
+  clean machine with just Python 3. It re-implements the judge logic; if you change judging behavior
+  in `judge.py`/`process.py`/`compare.py`, keep the runner core in sync. `run.sh` is its wrapper and
+  is placed at the package root by `packaging.py` so `./run.sh` works.
+- **A package never contains the author's source** (`solutions/`), the brute-force reference, or
+  `config/`. See `packaging.build_package`.
+- **Honesty is a feature.** Expected answers come from one peer's solution, not an authority. The
+  correctness disclaimer is always included in the generated README (`readme.py`). Smart suggestions
+  (`suggestions.py`) explain and ask - they never change behavior silently.
+- **Help text has one home.** `morvix/help_text.py` powers both `help` and the autocomplete meta
+  column; keep summaries there in sync with what a command actually does.
+
+## Style
+
+Comments are plain-English header blocks per file/function with occasional `# - bullet` lists for
+multi-step logic; sparse inline comments; no heavy docstrings. Keep code simple - this is open
+source and meant to be readable by a newcomer. Commit messages are conventional (`feat:`, `fix:`,
+`chore:`, `refactor:`, `docs:`, `test:`), lowercase, no body or trailers.

morvix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krzysztof Adamczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

morvix-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: morvix
+Version: 0.1.0
+Summary: A test-authoring, test-running, and test-sharing CLI for university programming assignments.
+Project-URL: Homepage, https://github.com/Krzysztof-Ad/morvix
+Project-URL: Repository, https://github.com/Krzysztof-Ad/morvix
+Author: Krzysztof Adamczyk
+License: MIT License
+        
+        Copyright (c) 2026 Krzysztof Adamczyk
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: assignments,cli,education,judge,testing,university
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Morvix
+
+A test-authoring, test-running, and test-sharing CLI for university programming assignments.
+
+Most courses don't hand out test suites, so students end up writing their own: they build test
+cases from their own solution, run their program against them, and share the cases on GitHub so
+classmates can check their code too. Morvix automates that whole loop - building, running, and
+sharing these self-made test harnesses - quickly and consistently, across languages and platforms.
+
+It's an honest tool. The "expected answers" come from one student's own solution, so passing every
+test does **not** prove a solution is correct - it proves it agrees with that one reference on the
+cases tried. Morvix says so plainly (it's baked into every package's README) and makes the real
+signal - lots of independent solutions agreeing - easy to see.
+
+> Morvix is not an online judge, not a grading server, and not an AI tool. It runs locally and
+> offline. Linux and macOS are the primary targets; Windows works on a best-effort basis.
+
+## Install
+
+```sh
+pip install morvix          # or, from a clone:
+pip install .
+```
+
+Needs Python 3.9+. The only dependencies are `prompt_toolkit` and `rich`. The runner that ships
+inside shared packages is pure standard library, so whoever you share with needs nothing but
+Python 3.
+
+## Quick start (the Author)
+
+Run `morvix` with no arguments to open the interactive shell (live autocomplete, history, a status
+bar), or use any command one-shot from your normal shell. What you can do one way is identical the
+other way.
+
+```sh
+cd my-assignment
+morvix init                       # create a project here (guided)
+morvix config cpp                 # how to build/run your language
+morvix import solution.cpp        # the solution under test
+morvix reference solution.cpp     # it also defines the expected answers
+morvix gen --random --count 100   # generate inputs from the built-in shapes
+morvix gen --expected             # compute answers by running the reference
+morvix run --all                  # build, run, judge - with a live table
+morvix runner new full            # a named, shareable run profile
+morvix package --zip              # bundle it up to share (your source is left out)
+```
+
+## Quick start (the Receiver)
+
+You got a package from a classmate. You don't need Morvix at all:
+
+```sh
+unzip their-tests.zip && cd their-tests
+./run.sh my_solution.cpp          # builds your code, runs every test, reports
+```
+
+If you *do* have Morvix, open it in the unpacked directory and you get the rich view - browse the
+tests, re-run selectively, and diff your per-case results against the author's.
+
+## What's in the box
+
+- **Languages**: C, C++, NASM, Python, Java, Rust - each a small adapter. Adding one is one file.
+- **Execution models**: `stdio`, `library` (link & assert), `args`, `file`, `interactive`.
+- **Comparison**: byte-exact, whitespace-insensitive, float-tolerant, hash, a custom checker, and
+  expected exit status / crash - combinable per case.
+- **Limits & checks**: wall/CPU time, peak memory (approximate), hard memory caps, output caps, and
+  an optional valgrind memory-correctness pass.
+- **Generation**: a built-in random-shape library, custom generators, stress testing against a
+  brute force, and crash-case candidates.
+- **Sharing**: zip / tar / tar.gz / tar.xz packages with an auto-generated README and a manifest.
+- **Workflows**: record a sequence of commands and replay it on the next assignment.
+
+These three axes - language, execution model, comparison - are kept independent, so they never
+multiply against each other. That's the design decision everything else hangs on.
+
+## Design
+
+The full design is in [documentation.md](documentation.md): the architecture, every command, the
+file formats, and the reasoning behind each choice.
+
+## License
+
+[MIT](LICENSE) (c) Krzysztof Adamczyk

morvix-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Morvix
+
+A test-authoring, test-running, and test-sharing CLI for university programming assignments.
+
+Most courses don't hand out test suites, so students end up writing their own: they build test
+cases from their own solution, run their program against them, and share the cases on GitHub so
+classmates can check their code too. Morvix automates that whole loop - building, running, and
+sharing these self-made test harnesses - quickly and consistently, across languages and platforms.
+
+It's an honest tool. The "expected answers" come from one student's own solution, so passing every
+test does **not** prove a solution is correct - it proves it agrees with that one reference on the
+cases tried. Morvix says so plainly (it's baked into every package's README) and makes the real
+signal - lots of independent solutions agreeing - easy to see.
+
+> Morvix is not an online judge, not a grading server, and not an AI tool. It runs locally and
+> offline. Linux and macOS are the primary targets; Windows works on a best-effort basis.
+
+## Install
+
+```sh
+pip install morvix          # or, from a clone:
+pip install .
+```
+
+Needs Python 3.9+. The only dependencies are `prompt_toolkit` and `rich`. The runner that ships
+inside shared packages is pure standard library, so whoever you share with needs nothing but
+Python 3.
+
+## Quick start (the Author)
+
+Run `morvix` with no arguments to open the interactive shell (live autocomplete, history, a status
+bar), or use any command one-shot from your normal shell. What you can do one way is identical the
+other way.
+
+```sh
+cd my-assignment
+morvix init                       # create a project here (guided)
+morvix config cpp                 # how to build/run your language
+morvix import solution.cpp        # the solution under test
+morvix reference solution.cpp     # it also defines the expected answers
+morvix gen --random --count 100   # generate inputs from the built-in shapes
+morvix gen --expected             # compute answers by running the reference
+morvix run --all                  # build, run, judge - with a live table
+morvix runner new full            # a named, shareable run profile
+morvix package --zip              # bundle it up to share (your source is left out)
+```
+
+## Quick start (the Receiver)
+
+You got a package from a classmate. You don't need Morvix at all:
+
+```sh
+unzip their-tests.zip && cd their-tests
+./run.sh my_solution.cpp          # builds your code, runs every test, reports
+```
+
+If you *do* have Morvix, open it in the unpacked directory and you get the rich view - browse the
+tests, re-run selectively, and diff your per-case results against the author's.
+
+## What's in the box
+
+- **Languages**: C, C++, NASM, Python, Java, Rust - each a small adapter. Adding one is one file.
+- **Execution models**: `stdio`, `library` (link & assert), `args`, `file`, `interactive`.
+- **Comparison**: byte-exact, whitespace-insensitive, float-tolerant, hash, a custom checker, and
+  expected exit status / crash - combinable per case.
+- **Limits & checks**: wall/CPU time, peak memory (approximate), hard memory caps, output caps, and
+  an optional valgrind memory-correctness pass.
+- **Generation**: a built-in random-shape library, custom generators, stress testing against a
+  brute force, and crash-case candidates.
+- **Sharing**: zip / tar / tar.gz / tar.xz packages with an auto-generated README and a manifest.
+- **Workflows**: record a sequence of commands and replay it on the next assignment.
+
+These three axes - language, execution model, comparison - are kept independent, so they never
+multiply against each other. That's the design decision everything else hangs on.
+
+## Design
+
+The full design is in [documentation.md](documentation.md): the architecture, every command, the
+file formats, and the reasoning behind each choice.
+
+## License
+
+[MIT](LICENSE) (c) Krzysztof Adamczyk