MRCV (Minimum Required Crystal Version)

MRCV (mrcv) is an automated, empirical CLI tool that determines the exact Minimum Required Crystal Version needed to build, test, and run your Crystal applications and shards.

Instead of guessing version bounds or relying on fragile syntactic AST heuristics, MRCV uses empirical binary bisection search across official Crystal compiler releases and calculates a deterministic 100-point Reliability Index.

Why MRCV?

Crystal uses whole-program semantic type inference and compile-time macros. Pure syntactic AST scanners (like Python's vermin) fail in Crystal because:

1. Uncalled Library Methods: The Crystal compiler never type-infers uncalled methods or uninstantiated generics if they are not reached from an entrypoint.
2. Macro Version Gating: Shards frequently use {% if compare_versions(Crystal::VERSION, "1.10.0") >= 0 %}. Static scanners cannot evaluate macro branches.
3. Grammar & Stdlib Drift: Standard library types, methods, and syntax evolution cannot be reliably verified without the specific compiler frontend.

MRCV solves this by running fast compilation checks (crystal build --no-codegen) and full test suites (crystal spec) in isolated rootless container environments (Podman/Docker) or local toolchains (mise/asdf).

Key Features

• Empirical Binary Search: Finds the minimum compiler floor across 20+ historical releases in $O(\log N)$ ($\approx 4\text{--}5$) checks.
• Sub-Second Fast Path: Uses crystal build --no-codegen to execute lexing, parsing, macro expansion, and full semantic type inference in milliseconds.
• 100-Point Reliability Index: Scores every version result across Verification Depth (50 pts), Matrix Contiguity (30 pts), and Spec Substance (20 pts), assigning Gold, Silver, Bronze, or Low confidence tiers.
• Contiguous Sweep Validation: Detects non-monotonic regressions, broken macro branches, or standard library deprecation holes.
• Rootless Podman by Default: Zero host contamination with automated :z volume isolation and shared shard caching.
• Structured Output: Supports rich human-readable terminal output and machine-parsable JSON (--format=json) for CI/CD integration.

Personas & Real-World Use Cases

MRCV is built to solve concrete operational friction across the software development lifecycle:

Reliability Index Tiers

Installation

From Source

git clone https://gitlab.com/renich/mrcv.git
cd mrcv
shards install
crystal build --release src/mrcv.cr -o bin/mrcv
sudo cp bin/mrcv /usr/local/bin/

Usage

# Basic empirical discovery on current project (rootless Podman)
mrcv

# Target a specific external shard or application directory
mrcv ../some_project

# Full runtime behavioral verification (executes `crystal spec` in containers)
mrcv --deep

# Force full contiguous forward sweep from minimum version to latest
mrcv --verify

# Fast bisection mode (skips forward sweep validation)
mrcv --fast

# Override candidate bounds to probe older or newer releases
mrcv --min-version 1.10.0 --max-version 1.21.0

# Air-gapped/offline execution (bypasses GitHub tags API)
mrcv --offline

# Use local toolchains (asdf/mise/$MRCV_CRYSTAL_PATH) instead of Podman
mrcv --runner=local

# Output machine-parsable JSON for CI/CD pipelines
mrcv --format=json

Example Output

Target:           my_project (Library)
Minimum Version:  1.12.2
Verified Range:   1.12.2 -> 1.21.0 (Contiguous: 10/10 versions PASSED)
Reliability:      95% [GOLD]

Breakdown:
  ✔ Verification:  Runtime test suite executed (`crystal spec`) [50/50]
  ✔ Contiguity:    100% contiguous sweep verified [30/30]
  ✔ Spec Quality:  Rich test suite detected (12 spec files) [15/20]
  ℹ Dependencies:  3 shards verified compatible

Development

# Install dependencies
shards install

# Run unit and integration specs
crystal spec

# Run linter
ameba

# Format code
crystal tool format

# Lint documentation
rstcheck $(find docs -name "*.rst") *.rst

Documentation

Full architectural documentation and modular specifications are maintained in docs/:

• Business Specifications:
  • Master Business Spec
  • User Personas
  • User Stories
  • Problematics & Pain Points
• Functional Specifications:
  • Master Functional Spec
  • CLI Interface
  • Version Detection & Bounds
  • Search Strategies
  • Reliability Indexing
• Technical Specifications:
  • Master Technical Spec
  • System Architecture
  • Container Runner
  • Search Engine
  • Reliability Engine
  • Shard Resolver
  • Compiler Reachability
• Architecture Decision Records:
  • Master ADR Index
  • ADR: Empirical Matrix Search Selection
• Project Roadmap & Audits:
  • Master Project Roadmap
  • Phase 1: Core Engine
  • Phase 2: Reliability Engine & Advanced
  • Phase 3: AST Blame, Diagnostics & Monorepo
  • Zero-Trust Forensic Audit Report

Contributing & Code of Honor

We welcome contributions! Please review our Contributing Guide and Universal Code of Honor before submitting merge requests.

Authors

• Rénich Bon Ćirić (@renich) - Creator and Maintainer

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later)/GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), and documentation is licensed under the GNU Free Documentation License v1.3 or later (GFDL-1.3-or-later) - see the LICENSE file for details.