Marker

Marker is an experimental code analysis interface, with the goal to create a stable and user-friendly linting framework for the Rust programming language. Creating custom lints should be a straightforward process, and using them should be as simple as declaring a new dependency.

Let's make custom lints and code analysis a reality!

Note

The project is in the early stages of development, some things are still missing and the API is still unstable.

A collection of features, goals and current limitations is available below.

Features

Custom Lints: Marker offers a framework for everyone to create and provide custom lints, allowing you to automatically improve the code quality for you and users of your crate.
User-Friendly Interface: Marker provides a new subcommand for Cargo that does all the heavy lifting for you. cargo_marker can automatically set up a driver for linting, compile lint crates and run them on any project.
Driver Independent: Every code analysis requires a driver that parses the code and provides further information. Marker's API is designed to be driver-independent, allowing it to support future compilers and potentially IDEs. (Currently, rustc is the only available driver)

And more to come, see Marker's goals and limitations below.

Usage

Prerequisites

cargo_marker requires Cargo and rustup to be installed. Currently, only Unix and Windows systems are supported. Linux, Windows, and macOS are actively tested in the CI.

Installation

cargo install cargo_marker

# Automatically setup the toolchain and driver
cargo marker setup --auto-install-toolchain

Specifying lints

Marker requires lint crates to be specified. The best way is to add them to the Cargo.toml file, like this:

[workspace.metadata.marker.lints]
# A local crate as a path
marker_lints = { path = './marker_lints' }
# An external crate via git
marker_lints = { git = "https://github.com/rust-marker/marker" }
# An external crate from a registry
marker_lints = "0.1.1"

Running Marker

Running Marker is as simple as running its sibling Clippy. Navigate to your Rust project directory and run the following command:

cargo marker

This will initialize Marker, compile the lint crates and start linting.

Goals

Stability: Marker's API design focuses on stability and extendability. The goal is to archive backwards compatibility, so that any lint, written after version 1.0.0, will compile and continue to work for years to come.
Usability: Marker's API focuses on usability, where possible under the constraints of Marker's stability guarantees. Types follow common design patterns and naming conventions, allowing you to focus on the lint logic directly.
Be A Foundation: Marker wants to be a foundation for new tools which make linting even easier, provide deeper code analysis capabilities and allow for automated migrations.

Limitations

Marker is still growing up, and that's a good thing. We can still shape the API and adapt it to what the user needs. However, this and the fact that Marker is not an official Rust project comes with some limitations:

Nightly: Internally, Marker has to rely on nightly versions of rustc. However, you, as an end-user, should not notice this dependency.
AST Limitations: Marker's API is still missing a few elements to represent everything required for linting. The API is still incomplete when it comes to:
- async/await expressions #174
- Higher order types
- Attributes #51
- Macros
- Item visibility #26
Utility: The API is currently lacking a lot of utility functions, to handle edge cases and make linting more pleasant.
Documentation: Marker still requires a lot of documentation, in the form of doc comments and a book, which explains the basic concept and works as a guide for end-users, lint- and marker-devs alike.

Development Timeline

Complete a draft of the API.
Improve documentation and conduct first user tests.
Update and expand the API to incorporate feedback.
Reach out to the wider community for more feedback.

The used nightly version will be updated every 6 weeks, when a new version of Rust is released.

Contributing

Contributions are highly appreciated! If you encounter any issues or have suggestions for improvements, please don't hesitate to open an issue. If you have an idea for a lint you want to implement with Marker, please share it by creating a user story.

Still reading? Interested in helping out? Wonderful! Check out Marker's contributor documentation

License

Rust-marker is distributed under the terms of the MIT license or the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT.

NathanFrasier / marker