runemark 0.1.1

Opinionated terminal presentation for Rust command-line tools
Documentation

runemark

Opinionated, human-readable terminal presentation for Rust command-line tools.

Runemark gives related CLI tools one consistent way to communicate progress, status, findings, and next steps. It owns presentation conventions—not command parsing, logging, domain models, or machine-readable report formats.

Status: 0.1 is the initial public release. The API remains intentionally small while it is validated in real CLI tools.

What it provides

Most command-line tools start with a mix of println!, ANSI snippets, and a progress bar. That works until the tool needs consistent CI output, color policy, grouped findings, compact summaries, detailed mode, or actionable next steps.

Runemark is the shared presentation layer for those concerns:

  • Semantic output: success, warning, error, info, muted text, and headings.
  • Predictable color policy: TTY-aware by default, NO_COLOR compliant, with explicit always and never modes.
  • Plain, deterministic output when redirected or snapshot-tested.
  • Report models for verdicts, summary metrics, finding groups, and next steps.
  • Actionable error blocks, file-change previews, and clickable locations for compatible terminals.
  • No runtime dependencies.

Install

Add the core presentation layer to a Rust project:

cargo add runemark

Quick start

use runemark::{ColorMode, Console, Tone};

let console = Console::stdout(ColorMode::Auto);

println!("{}", console.paint(Tone::Title, "site audit"));
println!("{}", console.paint(Tone::Warning, "3 findings need review"));
println!("{}", console.paint(Tone::Muted, "Run with --details for every finding."));

ColorMode::Auto emits styles only to an interactive terminal and honours the NO_COLOR convention. Use Always for a forced colorful local experience or Never for tests and plain logs.

Reports

Build reports from application-owned data and choose compact or detailed rendering in the host CLI. Runemark never defines domain-specific finding or machine-report types.

use runemark::{Finding, FindingGroup, Report, Tone, Verdict};

let report = Report::new("Site audit", Verdict::Warning).add_group(
    FindingGroup::new("Accessibility")
        .add_finding(Finding::new(Tone::Warning, "Image has no text alternative")),
);

print!("{}", report.render(runemark::Console::stdout(runemark::ColorMode::Auto)));

Design boundaries

Runemark owns Applications own
Terminal color policy and semantic tones CLI arguments and configuration
Compact human-readable report layout Domain finding types and business rules
Detail level conventions and next-step blocks JSON, SARIF, Markdown, HTML, and other artifacts
Line-oriented terminal presentation Logging, tracing, prompts, and full-screen TUIs

Roadmap

The initial API is deliberately narrow. Future additions are driven by real consumer needs rather than speculative abstractions:

  1. Validate the current API in real CLI tools before expanding it.

Development

Run the complete local validation suite:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features
cargo package --locked

See CONTRIBUTING.md for API and contribution guidelines.

License

Runemark is licensed under the MIT license (LICENSE).