opy-rs

opy-rs is WrightKit's standalone Rust implementation of the OverPy .opy language. It is intended to be useful on its own as a library and CLI for parsing, preprocessing, checking, inspecting, compiling, and eventually reconstructing supported OverPy projects.

Wright is a downstream consumer that integrates opy-rs with broader tooling such as linting, analysis, source editing, agent workflows, CI, and language services. An LPP provider in this repository is an integration role that opy-rs may expose to Wright and other tooling clients, not the reason this repository exists.

Canonical raw Workshop semantics are shared instead of reimplemented here. opy-rs owns OverPy syntax, preprocessing, macros, semantic resolution, OverPy-specific lowering, compiler behavior, diagnostics, provenance, and Workshop-to-OPY reconstruction. workshop-rs owns canonical Workshop catalog identities, WIR, validation, settings/localization data, raw Workshop parsing, and emission.

OPY source
   ↓
opy-rs parsing, preprocessing, and semantic HIR
   ↓
OPY semantic model / HIR
   ↓
opy-rs compiler + reconstruction logic
   ↓
workshop-rs canonical WIR / validation / emission
   ↓
Workshop text

The reverse path starts from Workshop text parsed by workshop-rs, then uses opy-rs-owned reconstruction logic to produce useful OverPy source. This architecture lets opy-rs remain a complete OverPy implementation without maintaining a second raw Workshop implementation.

Features

• OverPy source analysis: lexer, preprocessing, parser, semantic resolution, source-located diagnostics, and provenance across includes and macros.
• Preprocessing and macros: #!include, object- and function-like #!define, #!undef, settings blocks, and recorded #!postCompileHook.
• JavaScript macros: OverPy-compatible __script__("...") macros run in a bounded embedded QuickJS-NG runtime without Node.js.
• Tooling APIs: check, semantic inspection, source-aware queries, and validated source-edit foundations.
• Compiler integration: OPY semantic lowering into canonical workshop-rs WIR, with unsupported behavior kept explicit.
• Compatibility evidence: corpus fixtures, pinned oracle snapshots, semantic probes, and native differential tests.

CLI and library

The standalone CLI exposes both Workshop-independent tooling and the bounded Workshop compiler surface:

opy-cli check main.opy
opy-cli compile main.opy
opy-cli compile --format json main.opy
opy-cli inspect main.opy
opy-cli completion bash
opy-cli version

The first-party LPP process is available as opy-provider; it supports LPP 1.1 entry-based OPY project requests so clients do not need to enumerate includes:

cargo run --release -p opy-provider

See the provider contract for its capabilities and artifact format.

The Rust library surface, including the bounded Workshop compiler, lives in crates/opy-rs; opy-cli is the standalone executable surface. See the tooling API reference and current architecture routing for the durable boundary.

Compatibility

Compatibility targets observable OverPy semantics for the declared support surface, not byte-identical output, optimizer choices, formatting, temporary variables, or upstream internal architecture. Support claims are backed by the canonical language-support contract, its linked inventories, and pinned OverPy reference evidence.

Important

opy-rs follows the OverPy language. It does not introduce a WrightKit-only OPY dialect.

The exhaustive per-feature evidence, pinned denominator, and current status are maintained in the canonical human-readable support contract and its linked inventories.

Relationship with Wright

opy-rs can be used independently. Wright adds a unified product layer across OverPy, DEL/OSTW, and raw Workshop and may consume opy-rs through native Rust APIs and/or the Language Provider Protocol depending on the integration path. Wright-specific lint, analysis, agent, CI, LSP, and orchestration behavior does not belong in this repository unless it exposes a missing OverPy semantic capability that opy-rs itself should own.

Validation

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-targets --all-features
python3 -m unittest discover -s tools/overpy/tests

CI additionally exercises the JavaScript macro runtime on macOS and Windows. Oracle-dependent compatibility probes run separately from the normal Rust and Python test suites.

Documentation

Current architecture, compatibility evidence, APIs, HIR, provenance, and maintainer references are indexed in docs/README.md.

Contributing

This repository is part of the WrightKit multi-repository workspace. Follow the workspace-level AGENTS.md first, then this repository's local rules.

License

opy-rs is distributed under the GNU Affero General Public License v3.0 or later. See LICENSE.