bench: add e2e benchmarks for the grep tldr invocations

Cover the real-world grep usage shapes from the tldr page end-to-end
through uumain over a shared multi-MB corpus (plus a directory with a
binary file for -rI):

  search pattern, -F fixed string, -rI recursive ignoring binary,
  -C 3 context, -Hn --color=always, -o only-matching, -v invert,
  -Ei extended + ignore-case.

Kept alongside the pure-scan throughput benches (literal vs regex, no
match). A rare marker keeps matched output small so the full-file scan
dominates the timing.

.github/workflows/codspeed.yml

@@ -0,0 +1,37 @@
+name: CodSpeed
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+  # `workflow_dispatch` allows CodSpeed to trigger backtest
+  # performance analysis in order to generate initial data.
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  codspeed:
+    name: Run benchmarks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Rust toolchain, cache and cargo-codspeed binary
+        uses: moonrepo/setup-rust@v0
+        with:
+          channel: stable
+          cache-target: release
+          bins: cargo-codspeed
+
+      - name: Build the benchmark target(s)
+        run: cargo codspeed build
+
+      - name: Run the benchmarks
+        uses: CodSpeedHQ/action@v4
+        with:
+          mode: simulation
+          run: cargo codspeed run

.pre-commit-config.yaml

@@ -0,0 +1,55 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+exclude: ^tests/fixtures/
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-executables-have-shebangs
+      - id: check-json
+        exclude: '\.vscode/(cSpell|extensions)\.json' # cSpell.json and extensions.json use comments
+      - id: check-shebang-scripts-are-executable
+        exclude: '.+\.rs' # would be triggered by #![some_attribute]
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-yaml
+        args: [ --allow-multiple-documents ]
+      - id: destroyed-symlinks
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [ --fix=lf ]
+      - id: trailing-whitespace
+
+  - repo: local
+    hooks:
+      - id: rust-linting
+        name: Rust linting
+        description: Run cargo fmt on files included in the commit.
+        entry: cargo +stable fmt --
+        pass_filenames: true
+        types: [file, rust]
+        language: system
+      - id: rust-clippy
+        name: Rust clippy
+        description: Run cargo clippy on files included in the commit.
+        entry: cargo +stable clippy --workspace --all-targets --all-features -- -D warnings
+        pass_filenames: false
+        types: [file, rust]
+        language: system
+      - id: cargo-lock-check
+        name: Cargo.lock sync check
+        description: Ensure Cargo.lock and fuzz/Cargo.lock are up-to-date.
+        entry: bash -c 'for dir in . fuzz; do if [ -d "$dir" ]; then ( cd "$dir" && cargo fetch --quiet ); fi; done'
+        pass_filenames: false
+        files: 'Cargo\.(toml|lock)$'
+        language: system
+      - id: cspell
+        name: Code spell checker (cspell)
+        description: Run cspell to check for spelling errors (if available).
+        entry: bash -c 'if command -v cspell >/dev/null 2>&1; then cspell --no-must-find-files -- "$@"; else echo "cspell not found, skipping spell check"; exit 0; fi' --
+        pass_filenames: true
+        language: system
+
+ci:
+  skip: [rust-linting, rust-clippy, cargo-lock-check, cspell]

Cargo.toml

@@ -27,5 +27,10 @@ onig_sys = { version = "*", default-features = false }
 uucore = "0.8.0"
 walkdir = "2.5"
 
+[[bench]]
+name = "grep_bench"
+harness = false
+
 [dev-dependencies]
+criterion = { version = "4.7.0", package = "codspeed-criterion-compat" }
 uutests = "0.8.0"

README.md

@@ -4,6 +4,7 @@
 [![dependency status](https://deps.rs/repo/github/uutils/grep/status.svg)](https://deps.rs/repo/github/uutils/grep)
 
 [![CodeCov](https://codecov.io/gh/uutils/grep/branch/main/graph/badge.svg)](https://codecov.io/gh/uutils/grep)
+[![CodSpeed](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/uutils/grep?utm_source=badge)
 
 # Grep, now in Rust
 
@@ -29,10 +30,15 @@ cargo build --release
 cargo test
 ```
 
+## Pre-commit hooks
+
+This project uses [pre-commit](https://pre-commit.com); run `pre-commit install` to enable the git hooks.
+
 ## Known Issues
 
 * Does not take `LANG`, etc., into account for handling file encodings (non-UTF8 matches are treated as binary)
 * No localization support yet
+* Performances need to be improved
 
 ## Contributing
 

benches/grep_bench.rs

@@ -0,0 +1,128 @@
+// This file is part of the uutils grep package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use criterion::{Criterion, black_box, criterion_group, criterion_main};
+use std::ffi::OsString;
+use std::path::Path;
+
+/// Run grep end-to-end through the real `uumain` entry point. `args` are the
+/// arguments after the program name (flags, pattern, paths). The exit status is
+/// ignored — we only care about the work performed.
+fn run(args: &[&str]) {
+    let mut argv: Vec<OsString> = Vec::with_capacity(args.len() + 1);
+    argv.push(OsString::from("grep"));
+    argv.extend(args.iter().map(OsString::from));
+    let _ = uu_grep::uumain(argv.into_iter());
+}
+
+/// Build a multi-megabyte log-like corpus plus a directory holding it alongside
+/// a binary file. Every line contains `worker-<n>` and a `2024-…` timestamp; a
+/// rare `RAREHIT` marker appears on a handful of lines (≈ every 10000th).
+/// Returns `(dir, log_file)`.
+fn build_corpus() -> (std::path::PathBuf, std::path::PathBuf) {
+    let mut content = String::new();
+    for i in 0..80_000u32 {
+        if i % 10_000 == 0 {
+            content.push_str(&format!(
+                "2024-01-15 10:30:{:02} RAREHIT worker-{i} special marker seen\n",
+                i % 60
+            ));
+        } else if i % 100 == 0 {
+            content.push_str(&format!(
+                "2024-01-15 10:30:{:02} ERROR worker-{i} connection reset\n",
+                i % 60
+            ));
+        } else {
+            content.push_str(&format!(
+                "2024-01-15 10:30:{:02} INFO  worker-{i} request handled in {}ms\n",
+                i % 60,
+                i % 1000
+            ));
+        }
+    }
+    assert!(content.len() > 4 * 1024 * 1024);
+
+    let dir = std::env::temp_dir().join(format!("uu_grep_bench_{}", std::process::id()));
+    std::fs::create_dir_all(&dir).unwrap();
+    let log = dir.join("app.log");
+    std::fs::write(&log, &content).unwrap();
+
+    // A binary file (contains NUL) that also holds the marker, so `-I` has
+    // something to skip while recursing.
+    let mut binary = vec![0u8, 1, 2, 3];
+    binary.extend_from_slice(b"RAREHIT in binary blob");
+    binary.extend(std::iter::repeat_n(0u8, 4096));
+    std::fs::write(dir.join("data.bin"), &binary).unwrap();
+
+    (dir, log)
+}
+
+fn bench_e2e(c: &mut Criterion) {
+    let (dir, log) = build_corpus();
+    let file = log.to_str().unwrap();
+    let dir_str = dir.to_str().unwrap();
+
+    // Pure scanning throughput: `-q` with a pattern that never matches forces a
+    // full scan and produces no output. A literal (which a buffer-at-a-time
+    // searcher can accelerate) versus an extended-regex control (which cannot).
+    {
+        let mut group = c.benchmark_group("scan");
+        group.bench_function("literal_no_match", |b| {
+            b.iter(|| run(black_box(&["-q", "NONEXISTENT_TOKEN_XYZ", file])))
+        });
+        group.bench_function("regex_no_match", |b| {
+            b.iter(|| run(black_box(&["-q", "-E", "NON[0-9]EXISTENT_TOKEN", file])))
+        });
+        group.finish();
+    }
+
+    // Real invocation shapes from the `grep` tldr page, each scanning the whole
+    // corpus. The `RAREHIT` marker matches only a handful of lines, so output
+    // stays small while the full-file scan dominates.
+    {
+        let mut group = c.benchmark_group("usage");
+
+        // Search for a pattern within a file.
+        group.bench_function("search_pattern", |b| {
+            b.iter(|| run(black_box(&["RAREHIT", file])))
+        });
+        // Search for an exact string (-F).
+        group.bench_function("fixed_string", |b| {
+            b.iter(|| run(black_box(&["-F", "RAREHIT", file])))
+        });
+        // Recursive search ignoring binary files (-rI).
+        group.bench_function("recursive_no_binary", |b| {
+            b.iter(|| run(black_box(&["-rI", "RAREHIT", dir_str])))
+        });
+        // Print 3 lines of context (-C 3).
+        group.bench_function("context", |b| {
+            b.iter(|| run(black_box(&["-C", "3", "RAREHIT", file])))
+        });
+        // Filename + line number with forced color (-Hn --color=always).
+        group.bench_function("filename_lineno_color", |b| {
+            b.iter(|| run(black_box(&["-Hn", "--color=always", "RAREHIT", file])))
+        });
+        // Print only the matched text (-o).
+        group.bench_function("only_matching", |b| {
+            b.iter(|| run(black_box(&["-o", "RAREHIT", file])))
+        });
+        // Invert match (-v); `worker-` is on every line, so nothing is printed
+        // and this measures the full inverted scan.
+        group.bench_function("invert_match", |b| {
+            b.iter(|| run(black_box(&["-v", "worker-", file])))
+        });
+        // Extended regex, case-insensitive (-Ei).
+        group.bench_function("extended_icase", |b| {
+            b.iter(|| run(black_box(&["-Ei", "rarehit", file])))
+        });
+
+        group.finish();
+    }
+
+    let _ = std::fs::remove_dir_all(Path::new(dir_str));
+}
+
+criterion_group!(benches, bench_e2e);
+criterion_main!(benches);

src/lib.rs

@@ -3,9 +3,12 @@
 // For the full copyright and license information, please view the LICENSE
 // file that was distributed with this source code.
 
-mod context_buffer;
-mod line_buffer;
-mod matcher;
+#[doc(hidden)]
+pub mod context_buffer;
+#[doc(hidden)]
+pub mod line_buffer;
+#[doc(hidden)]
+pub mod matcher;
 mod output;
 mod searcher;
 
@@ -20,7 +23,8 @@ use std::path::Path;
 use uucore::error::{FromIo, UResult, USimpleError};
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum RegexMode {
+#[doc(hidden)]
+pub enum RegexMode {
     Fixed,
     Basic,
     Extended,
@@ -28,7 +32,8 @@ enum RegexMode {
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum BinaryMode {
+#[doc(hidden)]
+pub enum BinaryMode {
     Binary,
     Text,
     WithoutMatch,
@@ -42,79 +47,84 @@ enum ColorMode {
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum DirectoryMode {
+#[doc(hidden)]
+pub enum DirectoryMode {
     Read,
     Skip,
     Recurse,
 }
 
 #[derive(Clone, Copy, PartialEq, Eq)]
-enum DeviceMode {
+#[doc(hidden)]
+pub enum DeviceMode {
     Default,
     Read,
     Skip,
 }
 
-struct ColorConfig<'a> {
-    matched_selected: &'a str,
-    matched_context: &'a str,
-    filename: &'a str,
-    line_number: &'a str,
-    byte_offset: &'a str,
-    separator: &'a str,
-    selected_line: &'a str,
-    context_line: &'a str,
+#[doc(hidden)]
+pub struct ColorConfig<'a> {
+    pub matched_selected: &'a str,
+    pub matched_context: &'a str,
+    pub filename: &'a str,
+    pub line_number: &'a str,
+    pub byte_offset: &'a str,
+    pub separator: &'a str,
+    pub selected_line: &'a str,
+    pub context_line: &'a str,
 
-    reverse_video: bool,
-    no_erase: bool,
+    pub reverse_video: bool,
+    pub no_erase: bool,
 }
 
-struct GlobSet {
+#[doc(hidden)]
+pub struct GlobSet {
     patterns: Vec<glob::Pattern>,
 }
 
-struct Config<'a> {
+#[doc(hidden)]
+pub struct Config<'a> {
     // Searcher
-    directory_mode: DirectoryMode,
-    device_mode: DeviceMode,
-    follow_symlinks: bool,
-    include_globs: GlobSet,
-    exclude_globs: GlobSet,
-    exclude_dir_globs: GlobSet,
-    label: &'a str,
+    pub directory_mode: DirectoryMode,
+    pub device_mode: DeviceMode,
+    pub follow_symlinks: bool,
+    pub include_globs: GlobSet,
+    pub exclude_globs: GlobSet,
+    pub exclude_dir_globs: GlobSet,
+    pub label: &'a str,
     #[cfg(windows)]
-    strip_cr: bool,
-    binary_mode: BinaryMode,
-    max_count: Option<u64>,
-    before_context: usize,
-    after_context: usize,
-    has_context: bool,
+    pub strip_cr: bool,
+    pub binary_mode: BinaryMode,
+    pub max_count: Option<u64>,
+    pub before_context: usize,
+    pub after_context: usize,
+    pub has_context: bool,
 
     // Matcher
-    patterns: &'a [&'a str],
-    regex_mode: RegexMode,
-    ignore_case: bool,
-    invert_match: bool,
-    word_regexp: bool,
-    line_regexp: bool,
+    pub patterns: &'a [&'a str],
+    pub regex_mode: RegexMode,
+    pub ignore_case: bool,
+    pub invert_match: bool,
+    pub word_regexp: bool,
+    pub line_regexp: bool,
 
     // Output
-    quiet: bool,
-    count: bool,
-    show_filename: bool,
-    files_with_matches: bool,
-    files_without_match: bool,
-    only_matching: bool,
-    byte_offset: bool,
-    line_number: bool,
-    initial_tab: bool,
-    null_separator: bool,
-    null_data: bool,
-    line_buffered: bool,
-    no_messages: bool,
-    group_separator: Option<&'a str>,
-    use_color: bool,
-    color_config: ColorConfig<'a>,
+    pub quiet: bool,
+    pub count: bool,
+    pub show_filename: bool,
+    pub files_with_matches: bool,
+    pub files_without_match: bool,
+    pub only_matching: bool,
+    pub byte_offset: bool,
+    pub line_number: bool,
+    pub initial_tab: bool,
+    pub null_separator: bool,
+    pub null_data: bool,
+    pub line_buffered: bool,
+    pub no_messages: bool,
+    pub group_separator: Option<&'a str>,
+    pub use_color: bool,
+    pub color_config: ColorConfig<'a>,
 }
 
 #[uucore::main(no_signals)]
@@ -854,8 +864,21 @@ fn expand_num_shorthand(args: impl Iterator<Item = OsString>) -> Vec<OsString> {
     out
 }
 
+impl Default for GlobSet {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
 impl GlobSet {
-    fn with_capacity(capacity: usize) -> Self {
+    /// Create an empty GlobSet.
+    pub fn new() -> Self {
+        Self {
+            patterns: Vec::new(),
+        }
+    }
+
+    pub fn with_capacity(capacity: usize) -> Self {
         Self {
             patterns: Vec::with_capacity(capacity),
         }