test: basic fuzzing (#407)

* test: setup fuzzing

* style: fmt

* style: reorder workspace members

* chore: set fuzz package name to logos-fuzz

* docs: fuzzing

* chore: make fuzzer private

* docs: mention fuzzing definition

Co-authored-by: Jérome Eertmans <[email protected]>

* docs(book): style logos to be bold

Co-authored-by: Jérome Eertmans <[email protected]>

* docs(book/fuzzing): style, more notes about subcommands, reporting info.

Co-authored-by: Jérome Eertmans <[email protected]>

* chore: fix fuzz crate metadata

* chore(msrv): bump to 1.70.0

* fix: msrv should also be duplicated

---------

Co-authored-by: Jérome Eertmans <[email protected]>

.gitignore

@@ -2,3 +2,6 @@
 /book/book
 **/*.rs.bk
 Cargo.lock
+
+# ignore output fuzzing
+out

Cargo.toml

@@ -1,5 +1,5 @@
 [workspace]
-members = ["logos-cli", "logos-codegen", "logos-derive", "tests"]
+members = ["logos-cli", "logos-codegen", "logos-derive", "tests", "fuzz"]
 resolver = "2"
 
 [workspace.package]
@@ -12,7 +12,7 @@ keywords = ["lexer", "lexical", "tokenizer", "parser", "no_std"]
 license = "MIT OR Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/maciejhirsz/logos"
-rust-version = "1.65.0"
+rust-version = "1.70.0"
 version = "0.14.1"
 
 [package]
@@ -30,7 +30,7 @@ rust-version.workspace = true
 version.workspace = true
 
 [package.metadata]
-msrv = "1.65.0"  # Needed to duplicate, because cargo-msrv does not support workspace
+msrv = "1.70.0"  # Needed to duplicate, because cargo-msrv does not support workspace
 
 [package.metadata.release]
 pre-release-replacements = [

book/src/SUMMARY.md

@@ -18,3 +18,4 @@
 + [Contributing](./contributing.md)
   + [Setup](./contributing/setup.md)
   + [Internals](./contributing/internals.md)
+  + [Fuzzing](./contributing/fuzzing.md)

book/src/contributing/fuzzing.md

@@ -0,0 +1,51 @@
+# Fuzzing
+
+
+Fuzzing is a technique to test a piece of software by injecting randomly generated inputs. This can be pretty useful to discover bugs, as pointed out in [#407](https://github.com/maciejhirsz/logos/pull/407).
+
+**Logos**' fuzzing crate is powered by [afl.rs](https://github.com/rust-fuzz/afl.rs) that
+finds panics in **Logos**' methods.
+
+## Usage
+
+First, make sure you have `cargo-afl` installed,
+[see the rust-fuzz afl setup guide for installation information](https://rust-fuzz.github.io/book/afl/setup.html).
+
+Next, change your current working directory to be the `fuzz` folder.
+
+### Building
+
+Before fuzzing, you need to build the target with:
+
+```bash
+cargo afl build
+```
+
+### Fuzzy testing
+
+The recommended way the run tests is with:
+
+```bash
+cargo afl fuzz -i in -o out ../target/debug/logos-fuzz
+```
+
+Note that it may run for a (very) long time before
+it encounter any bug.
+
+## Replaying a Crash
+
+If you happen to find a bug that crashes the program,
+you can reply it with
+
+```bash
+cargo afl run logos-fuzz < out/default/crashes/crash_file
+```
+
+### Reporting a Bug
+
+If you encounter a crash and you feel the error message
+is not appropriate,
+please report it by opening
+[an issue](https://github.com/maciejhirsz/logos/issues/new).
+Don't forget to include your crash file so we can later
+reproduce it.

book/src/contributing/internals.md

@@ -22,3 +22,6 @@
   and usage help can be obtained through the `logos-cli --help` command.
   This tool can be useful if your tokens definition stays is constant, and
   you want to reduce compilatio time overhead caused by derive macros.
++ `logos-fuzz` is an internal crate that uses [afl.rs](https://github.com/rust-fuzz/afl.rs)
+  to find confusing panics before they reach the developer.
+  To use this tool, see the [Fuzzing guide]('./fuzzing.md')

fuzz/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "logos-fuzz"
+authors.workspace = true
+categories.workspace = true
+description.workspace = true
+edition.workspace = true
+homepage.workspace = true
+keywords.workspace = true
+license.workspace = true
+readme.workspace = true
+repository.workspace = true
+rust-version.workspace = true
+version.workspace = true
+publish = false
+
+[dependencies]
+afl = "0.15"
+arbitrary = "1.3"
+logos-codegen = { path = "../logos-codegen", features = ["fuzzing"] }
+
+[package.metadata.release]
+shared-version = true

fuzz/in/literal

@@ -0,0 +1 @@
+literal

fuzz/in/regex

@@ -0,0 +1 @@
+a+b[cd-h]+?

fuzz/src/main.rs

@@ -0,0 +1,16 @@
+use afl::fuzz;
+use logos_codegen::{
+    graph::{Graph, Node},
+    mir::Mir,
+};
+
+fn main() {
+    fuzz!(|regex: String| {
+        let mut graph = Graph::new();
+
+        if let Ok(mir) = Mir::utf8(&regex) {
+            let leaf = graph.push(Node::Leaf("LEAF"));
+            let _ = graph.regex(mir, leaf);
+        }
+    });
+}

logos-codegen/Cargo.toml

@@ -14,6 +14,8 @@ rstest = "0.18.2"
 [features]
 # Enables debug messages
 debug = []
+# Exports out internal methods for fuzzing
+fuzzing = []
 
 [lib]
 bench = false

logos-codegen/src/lib.rs

@@ -10,9 +10,15 @@
 
 mod error;
 mod generator;
+#[cfg(not(feature = "fuzzing"))]
 mod graph;
+#[cfg(feature = "fuzzing")]
+pub mod graph;
 mod leaf;
+#[cfg(not(feature = "fuzzing"))]
 mod mir;
+#[cfg(feature = "fuzzing")]
+pub mod mir;
 mod parser;
 mod util;