mushy-peas

mushy-peas is a typed Python toolkit for reading, writing, inspecting, and analyzing PennMUSH data. It handles PennMUSH database files and provides a separate analysis pipeline for PennMUSH softcode source trees.

The database toolkit supports:

• current labeled main object databases;
• readable oldstyle main databases covered by PennMUSH dbtools;
• mail databases, including mail aliases;
• current and oldstyle chat databases;
• uncompressed, gzip, bzip2, and explicitly configured external-filter streams; and
• structured JSON output, canonical rewrites, and oldstyle upgrades.

The softcode toolkit inventories source trees, builds concrete and abstract syntax views, projects semantic graphs, reports parser coverage and diagnostics, and can compare parser behavior with an instrumented PennMUSH server.

This project targets PennMUSH's on-disk formats and softcode semantics. It is not a LambdaMOO parser or a cross-server database converter.

Requirements and installation

mushy-peas requires Python 3.11 or newer and uses uv for environments and commands.

git clone https://github.com/ctoth/mushy-peas.git
cd mushy-peas
uv sync --dev

Run installed commands from the checkout with uv run:

uv run mush-inspect --help

Database quick start

Inspect a database. The default --kind auto mode detects main, mail, or chat input:

uv run mush-inspect tests/fixtures/main/current_objects.db

The output is a compact summary suitable for scripts or a first compatibility check:

kind: main
format_kind: main-current
dbversion: 6
object_count: 3
non_garbage_count: 2
flag_count: 0
power_count: 0
global_attribute_count: 0

Write canonical output and report how many lines differ from the input:

uv run mush-roundtrip world.db --out world.roundtrip.db

Dump the complete parsed model as JSON:

uv run mush-dump-json world.db > world.json

Upgrade readable oldstyle main or chat data to the current canonical format:

uv run mush-upgrade oldstyle.db --kind main-oldstyle --out current.db
uv run mush-upgrade oldchat.db --kind chat-oldstyle --out current-chat.db

Parse failures exit nonzero and include source file and line context.

Database commands

• mush-inspect PATH [--kind main|mail|chat|auto] prints format and record counts.
• mush-roundtrip PATH --out OUT [--kind main|mail|chat|auto] reads and rewrites a database, then reports the line-difference count.
• mush-dump-json PATH [--kind main|mail|chat|auto] serializes the complete parsed database model as JSON.
• mush-upgrade PATH --kind main-oldstyle|chat-oldstyle --out OUT converts a supported oldstyle database to current canonical output.

Softcode analysis

Softcode commands accept one or more files or directories. Their machine- readable commands print JSON to standard output, so results can be redirected to files without a separate output option:

uv run mush-softcode-inventory path/to/softcode > inventory.json
uv run mush-softcode-parse path/to/softcode > parsed.json
uv run mush-softcode-graph path/to/softcode > graph.json
uv run mush-softcode-coverage path/to/softcode > coverage.json
uv run mush-softcode-report path/to/softcode > coverage.md

The installed analysis commands are:

• mush-softcode-inventory PATH [PATH ...] discovers source files and extracts command, function, attribute, lock, and other candidate units.
• mush-softcode-parse PATH [PATH ...] [--functions FUNCTIONS] emits each unit's concrete syntax tree, AST view, and command/action views.
• mush-softcode-graph PATH [PATH ...] builds definitions, command surfaces, references, attribute reads and writes, object references, q-register and RPC references, and effects.
• mush-softcode-coverage PATH [PATH ...] emits JSON counts for parsing, round-tripping, diagnostics, graph projections, unsupported dynamic forms, corpus seeds, and oracle-agreement fixtures.
• mush-softcode-report PATH [PATH ...] renders the same coverage model as Markdown. Both coverage commands accept --functions, --seeds, and --oracle-agreement fixtures.
• mush-softcode-functions PENNMUSH_CHECKOUT --output OUT --pennmush-commit COMMIT generates function metadata from a specific PennMUSH checkout and records the source commit.
• mush-softcode-trace EXPRESSION runs an expression through the instrumented PennMUSH process_expression() oracle and returns its result and parse events as JSON. This command requires the local WSL/PennMUSH oracle environment described in docs/softcode-oracle.md.

See docs/softcode-parser-plan.md for the parser architecture, evidence model, and slice-by-slice implementation status.

Compatibility evidence

The test suite combines hand-written source-shaped fixtures, property tests, cross-family read/write/read checks, and external PennMUSH oracles:

• current and oldstyle main databases;
• mail databases and aliases;
• current and oldstyle chat databases;
• uncompressed, gzip, bzip2, and external-filter streams;
• canonical round trips and oldstyle upgrades;
• softcode expression, action, lock, graph, and diagnostic behavior; and
• generated main/mail/chat files loaded by a real PennMUSH server when the local WSL checkout is available.

Fixture and server-oracle provenance is documented in tests/fixtures/README.md.

Development

Run the complete local gate with uv:

uv run ruff check .
uv run mypy .
uv run pyright
uv run pytest

The repository enforces strict mypy and pyright settings, Ruff checks, a local post-commit hook, and the same validation in GitHub Actions.