Revert "perf: buffer-at-a-time search for literal patterns"

fuzz: add differential fuzzer against GNU grep

.github/workflows/GnuComment.yml

@@ -0,0 +1,83 @@
+name: GnuComment
+
+# Post the GNU grep testsuite comparison (produced by the GnuTests workflow)
+# as a comment on the pull request.
+
+on:
+  workflow_run:
+    workflows: ["GnuTests"]
+    types:
+      - completed
+
+permissions: {}
+jobs:
+  post-comment:
+    permissions:
+      actions: read  #  to list workflow run artifacts
+      pull-requests: write  #  to comment on the pr
+
+    runs-on: ubuntu-latest
+    if: >
+      github.event.workflow_run.event == 'pull_request'
+    steps:
+      - name: 'Download artifact'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // List all artifacts from GnuTests
+            var artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              run_id: ${{ github.event.workflow_run.id }},
+            });
+
+            // Download the "comment" artifact, which contains a PR number (NR) and result.txt
+            var matchArtifact = artifacts.data.artifacts.filter((artifact) => {
+              return artifact.name == "comment"
+            })[0];
+
+            if (!matchArtifact) {
+              console.log('No comment artifact found');
+              return;
+            }
+
+            var download = await github.rest.actions.downloadArtifact({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              artifact_id: matchArtifact.id,
+              archive_format: 'zip',
+            });
+            var fs = require('fs');
+            fs.writeFileSync('${{ github.workspace }}/comment.zip', Buffer.from(download.data));
+      - run: unzip comment.zip || echo "Failed to unzip comment artifact"
+
+      - name: 'Comment on PR'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            var fs = require('fs');
+
+            // Check if files exist
+            if (!fs.existsSync('./NR')) {
+              console.log('No NR file found, skipping comment');
+              return;
+            }
+            if (!fs.existsSync('./result.txt')) {
+              console.log('No result.txt file found, skipping comment');
+              return;
+            }
+
+            var issue_number = Number(fs.readFileSync('./NR'));
+            var content = fs.readFileSync('./result.txt');
+
+            if (content.toString().trim().length > 7) { // 7 because we have backquote + \n
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issue_number,
+                body: 'GNU grep testsuite comparison:\n```\n' + content + '```'
+              });
+            } else {
+              console.log('Comment content too short, skipping');
+            }

.github/workflows/GnuTests.yml

@@ -0,0 +1,197 @@
+name: GnuTests
+
+# Run the upstream GNU grep testsuite against the Rust grep implementation to
+# track and guard byte-for-byte compatibility. See util/run-gnu-testsuite.sh.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - '*'
+
+permissions:
+  contents: write # Publish grep instead of discarding
+
+# End the current execution if there is a new changeset in the PR.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+env:
+  DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+  TEST_FULL_SUMMARY_FILE: 'grep-gnu-full-result.json'
+
+jobs:
+  native:
+    name: Run GNU grep testsuite
+    runs-on: ubuntu-24.04
+    steps:
+    - name: Checkout code (grep)
+      uses: actions/checkout@v4
+      with:
+        path: 'grep'
+        persist-credentials: false
+    - uses: dtolnay/rust-toolchain@master
+      with:
+        toolchain: stable
+    - uses: Swatinem/rust-cache@v2
+      with:
+        workspaces: "./grep -> target"
+
+    - name: Fetch GNU grep testsuite
+      shell: bash
+      run: |
+        ## Download and extract the upstream GNU grep release tarball
+        mkdir -p gnu.grep
+        cd gnu.grep
+        bash ../grep/util/fetch-gnu.sh
+
+    - name: Build Rust grep binary
+      shell: bash
+      run: |
+        cd 'grep'
+        cargo build --release --config=profile.release.strip=true
+        tar -C target/release -cf - grep | zstd -19 -o ../grep-x86_64-unknown-linux-gnu.tar.zst
+    - name: Publish latest commit
+      uses: softprops/action-gh-release@v3
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      with:
+        tag_name: latest-commit
+        body: |
+          commit: ${{ github.sha }}
+        draft: false
+        prerelease: true
+        files: |
+          grep-x86_64-unknown-linux-gnu.tar.zst
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Run GNU grep testsuite
+      shell: bash
+      run: |
+        cd 'grep'
+        export GNU_GREP_DIR="../gnu.grep"
+        ./util/run-gnu-testsuite.sh --json-output "${{ env.TEST_FULL_SUMMARY_FILE }}" || true
+
+    - name: Upload full json results
+      uses: actions/upload-artifact@v4
+      with:
+        name: grep-gnu-full-result
+        path: grep/${{ env.TEST_FULL_SUMMARY_FILE }}
+        if-no-files-found: warn
+
+  aggregate:
+    needs: [native]
+    permissions:
+      actions: read
+      contents: read
+      pull-requests: read
+    name: Aggregate GNU test results
+    runs-on: ubuntu-24.04
+    steps:
+    - name: Initialize workflow variables
+      id: vars
+      shell: bash
+      run: |
+        ## VARs setup
+        outputs() { step_id="${{ github.action }}"; for var in "$@" ; do echo steps.${step_id}.outputs.${var}="${!var}"; echo "${var}=${!var}" >> $GITHUB_OUTPUT; done; }
+        TEST_SUMMARY_FILE='grep-gnu-result.json'
+        outputs TEST_SUMMARY_FILE
+
+    - name: Checkout code (grep)
+      uses: actions/checkout@v4
+      with:
+        path: 'grep'
+        persist-credentials: false
+
+    - name: Retrieve reference artifacts
+      uses: dawidd6/action-download-artifact@v6
+      continue-on-error: true
+      with:
+        workflow: GnuTests.yml
+        branch: "${{ env.DEFAULT_BRANCH }}"
+        workflow_conclusion: completed
+        path: "reference"
+        if_no_artifact_found: warn
+
+    - name: Download full json results
+      uses: actions/download-artifact@v4
+      with:
+        name: grep-gnu-full-result
+        path: results
+
+    - name: Extract/summarize testing info
+      id: summary
+      shell: bash
+      run: |
+        ## Extract/summarize testing info
+        outputs() { step_id="${{ github.action }}"; for var in "$@" ; do echo steps.${step_id}.outputs.${var}="${!var}"; echo "${var}=${!var}" >> $GITHUB_OUTPUT; done; }
+
+        RESULT_FILE="results/${{ env.TEST_FULL_SUMMARY_FILE }}"
+        if [[ ! -f "$RESULT_FILE" ]]; then
+          echo "::error ::Result file $RESULT_FILE not found"
+          find results -type f || true
+          exit 1
+        fi
+
+        TOTAL=$(jq -r '.summary.total // 0' "$RESULT_FILE")
+        PASS=$(jq -r '.summary.passed // 0' "$RESULT_FILE")
+        FAIL=$(jq -r '.summary.failed // 0' "$RESULT_FILE")
+        SKIP=$(jq -r '.summary.skipped // 0' "$RESULT_FILE")
+
+        output="GNU grep tests summary = TOTAL: $TOTAL / PASS: $PASS / FAIL: $FAIL / SKIP: $SKIP"
+        echo "${output}"
+        if [[ "$FAIL" -gt 0 ]]; then
+          echo "::warning ::${output}"
+        fi
+
+        outputs TOTAL PASS FAIL SKIP
+
+    - name: Compare test failures VS reference
+      shell: bash
+      run: |
+        ## Compare current results against the reference summary from the default branch
+        REF_SUMMARY_FILE='reference/grep-gnu-full-result/${{ env.TEST_FULL_SUMMARY_FILE }}'
+        CURRENT_SUMMARY_FILE="results/${{ env.TEST_FULL_SUMMARY_FILE }}"
+        IGNORE_INTERMITTENT="grep/.github/workflows/ignore-intermittent.txt"
+
+        # Set up comment directory for the GnuComment workflow.
+        COMMENT_DIR="reference/comment"
+        mkdir -p ${COMMENT_DIR}
+        echo ${{ github.event.number }} > ${COMMENT_DIR}/NR
+        COMMENT_LOG="${COMMENT_DIR}/result.txt"
+        : > "${COMMENT_LOG}"
+
+        COMPARISON_RESULT=0
+        if test -f "${REF_SUMMARY_FILE}"; then
+          python3 grep/util/compare_test_results.py \
+            --ignore-file "${IGNORE_INTERMITTENT}" \
+            --output "${COMMENT_LOG}" \
+            "${CURRENT_SUMMARY_FILE}" "${REF_SUMMARY_FILE}" || COMPARISON_RESULT=$?
+        else
+          echo "::warning ::Skipping test comparison; no prior reference summary at '${REF_SUMMARY_FILE}'."
+        fi
+
+        if [ ${COMPARISON_RESULT} -eq 1 ]; then
+          echo "::error ::Found new non-intermittent test failures"
+          UPLOAD_EXIT=1
+        else
+          echo "::notice ::No new test failures detected"
+          UPLOAD_EXIT=0
+        fi
+        echo "UPLOAD_EXIT=${UPLOAD_EXIT}" >> $GITHUB_ENV
+
+    - name: Upload comparison log (for GnuComment workflow)
+      if: success() || failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: comment
+        path: reference/comment/
+
+    - name: Report test results
+      if: success() || failure()
+      shell: bash
+      run: |
+        echo "::notice ::GNU grep testsuite: TOTAL ${{ steps.summary.outputs.TOTAL }} / PASS ${{ steps.summary.outputs.PASS }} / FAIL ${{ steps.summary.outputs.FAIL }} / SKIP ${{ steps.summary.outputs.SKIP }}"
+        # Fail the job if the comparison found new non-intermittent regressions.
+        exit "${UPLOAD_EXIT:-0}"

.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

.github/workflows/fuzzing.yml

@@ -0,0 +1,162 @@
+name: Fuzzing
+
+# spell-checker:ignore (people) taiki-e
+# spell-checker:ignore (misc) fuzzer uufuzz
+
+env:
+  CARGO_INCREMENTAL: "0"
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+permissions:
+  contents: read # to fetch code (actions/checkout)
+
+# End the current execution if there is a new changeset in the PR.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  uufuzz-examples:
+    name: Build and test uufuzz examples
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@stable
+    - name: Build uufuzz library
+      run: |
+        cd fuzz/uufuzz
+        cargo build --release
+    - name: Run uufuzz tests
+      run: |
+        cd fuzz/uufuzz
+        cargo test --lib
+    - name: Build and run uufuzz examples
+      run: |
+        cd fuzz/uufuzz
+        echo "Building all examples..."
+        cargo build --examples --release
+
+        # Run all examples except integration_testing (which has FD issues in CI)
+        for example in examples/*.rs; do
+          example_name=$(basename "$example" .rs)
+          if [ "$example_name" != "integration_testing" ]; then
+            cargo run --example "$example_name" --release
+          fi
+        done
+
+  fuzz-build:
+    name: Build the fuzzers
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@stable
+    - name: Install `cargo-fuzz`
+      uses: taiki-e/install-action@v2
+      with:
+        tool: cargo-fuzz
+    - name: Emulate a nightly toolchain
+      run: |
+        echo "RUSTC_BOOTSTRAP=1" >> "${GITHUB_ENV}"
+    - name: Run `cargo-fuzz build`
+      # Force the correct target
+      # https://github.com/rust-fuzz/cargo-fuzz/issues/398
+      run: cargo fuzz build --target $(rustc --print host-tuple)
+
+  fuzz-run:
+    needs: fuzz-build
+    name: Fuzz
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    env:
+      RUN_FOR: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        test-target:
+          # fuzz_grep is a differential fuzzer against GNU grep; it currently
+          # surfaces compatibility differences, so it is not expected to pass yet.
+          - { name: fuzz_grep, should_pass: false }
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@stable
+    - name: Install `cargo-fuzz`
+      uses: taiki-e/install-action@v2
+      with:
+        tool: cargo-fuzz
+    - name: Emulate a nightly toolchain
+      run: |
+        echo "RUSTC_BOOTSTRAP=1" >> "${GITHUB_ENV}"
+    - name: Run ${{ matrix.test-target.name }} for ${{ env.RUN_FOR }} seconds
+      id: run_fuzzer
+      shell: bash
+      continue-on-error: ${{ !matrix.test-target.should_pass }}
+      run: |
+        mkdir -p fuzz/stats
+        STATS_FILE="fuzz/stats/${{ matrix.test-target.name }}.txt"
+        # Force the correct target
+        # https://github.com/rust-fuzz/cargo-fuzz/issues/398
+        cargo fuzz run --target $(rustc --print host-tuple) ${{ matrix.test-target.name }} -- -max_total_time=${{ env.RUN_FOR }} -timeout=${{ env.RUN_FOR }} -detect_leaks=0 -print_final_stats=1 2>&1 | tee "$STATS_FILE"
+
+        # Save should_pass value for later inspection
+        echo "${{ matrix.test-target.should_pass }}" > "fuzz/stats/${{ matrix.test-target.name }}.should_pass"
+
+        # Print stats to job output for immediate visibility
+        echo "----------------------------------------"
+        echo "FUZZING STATISTICS FOR ${{ matrix.test-target.name }}"
+        echo "----------------------------------------"
+        echo "Runs:           $(grep -q "stat::number_of_executed_units" "$STATS_FILE" && grep "stat::number_of_executed_units" "$STATS_FILE" | awk '{print $2}' || echo "unknown")"
+        echo "Execution Rate: $(grep -q "stat::average_exec_per_sec" "$STATS_FILE" && grep "stat::average_exec_per_sec" "$STATS_FILE" | awk '{print $2}' || echo "unknown") execs/sec"
+        echo "New Units:      $(grep -q "stat::new_units_added" "$STATS_FILE" && grep "stat::new_units_added" "$STATS_FILE" | awk '{print $2}' || echo "unknown")"
+        echo "Expected:       ${{ matrix.test-target.should_pass }}"
+        if grep -q "SUMMARY: " "$STATS_FILE"; then
+          echo "Status:         $(grep "SUMMARY: " "$STATS_FILE" | head -1)"
+        else
+          echo "Status:         Completed"
+        fi
+        echo "----------------------------------------"
+
+        # Add summary to GitHub step summary
+        echo "### Fuzzing Results for ${{ matrix.test-target.name }}" >> "$GITHUB_STEP_SUMMARY"
+        echo "" >> "$GITHUB_STEP_SUMMARY"
+        echo "| Metric | Value |" >> "$GITHUB_STEP_SUMMARY"
+        echo "|--------|-------|" >> "$GITHUB_STEP_SUMMARY"
+        if grep -q "stat::number_of_executed_units" "$STATS_FILE"; then
+          echo "| Runs | $(grep "stat::number_of_executed_units" "$STATS_FILE" | awk '{print $2}') |" >> "$GITHUB_STEP_SUMMARY"
+        fi
+        if grep -q "stat::average_exec_per_sec" "$STATS_FILE"; then
+          echo "| Execution Rate | $(grep "stat::average_exec_per_sec" "$STATS_FILE" | awk '{print $2}') execs/sec |" >> "$GITHUB_STEP_SUMMARY"
+        fi
+        if grep -q "stat::new_units_added" "$STATS_FILE"; then
+          echo "| New Units | $(grep "stat::new_units_added" "$STATS_FILE" | awk '{print $2}') |" >> "$GITHUB_STEP_SUMMARY"
+        fi
+        echo "| Should pass | ${{ matrix.test-target.should_pass }} |" >> "$GITHUB_STEP_SUMMARY"
+        if grep -q "SUMMARY: " "$STATS_FILE"; then
+          echo "| Status | $(grep "SUMMARY: " "$STATS_FILE" | head -1) |" >> "$GITHUB_STEP_SUMMARY"
+        else
+          echo "| Status | Completed |" >> "$GITHUB_STEP_SUMMARY"
+        fi
+        echo "" >> "$GITHUB_STEP_SUMMARY"
+    - name: Upload Stats
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: fuzz-stats-${{ matrix.test-target.name }}
+        path: |
+          fuzz/stats/${{ matrix.test-target.name }}.txt
+          fuzz/stats/${{ matrix.test-target.name }}.should_pass
+        retention-days: 5

.github/workflows/ignore-intermittent.txt

@@ -0,0 +1,7 @@
+# List of intermittent test names to ignore in result comparisons
+# Format: one test name per line, lines starting with # are comments
+#
+# Add test names that are known to be flaky or environment-dependent
+# Example:
+# basic_substitution
+# line_address_test

.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,12 +4,30 @@
 [![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
 
 A Rust implementation of [GNU Grep](https://www.gnu.org/software/grep/).
 This project is an initial release and may contain bugs.
 
+## Install
+
+```shell
+cargo install uu_grep
+```
+
+## 🚀 Try it online
+
+You can try `grep` directly in your browser on the [uutils playground](https://uutils.github.io/playground/).
+Arguments (and a full command) can be passed through the URL via the `cmd` query parameter, for example:
+
+```shell
+printf '🚀 rocket\n🛰️ satellite\n🌙 moon\n⭐ star\n' | grep 🌙
+```
+
+[Run it in the playground](https://uutils.github.io/playground/?cmd=printf%20%27%F0%9F%9A%80%20rocket%5Cn%F0%9F%9B%B0%EF%B8%8F%20satellite%5Cn%F0%9F%8C%99%20moon%5Cn%E2%AD%90%20star%5Cn%27%20%7C%20grep%20%F0%9F%8C%99)
+
 ## Building
 
 Download Rust at: https://rustup.rs/
@@ -29,10 +47,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);

fuzz/.cargo/config.toml

@@ -0,0 +1,2 @@
+[build]
+rustflags = ["--cfg", "fuzzing"]

fuzz/.gitignore

@@ -0,0 +1,4 @@
+target
+corpus
+artifacts
+Cargo.lock

fuzz/Cargo.toml

@@ -0,0 +1,33 @@
+[package]
+name = "uu_grep-fuzz"
+version = "0.0.0"
+description = "uutils ~ 'grep' fuzzers"
+repository = "https://github.com/microsoft/uutils-grep/tree/main/fuzz/"
+edition = "2024"
+rust-version = "1.88.0"
+license = "MIT"
+publish = false
+
+[package.metadata]
+cargo-fuzz = true
+
+# Prevent this from interfering with the parent workspace
+[workspace]
+members = ["."]
+
+# Enable debug symbols in release builds for readable backtraces
+# when fuzzing discovers crashes.
+[profile.release]
+debug = true
+
+[dependencies]
+libfuzzer-sys = "0.4.7"
+rand = { version = "0.10.1", features = ["std_rng"] }
+uufuzz = { path = "uufuzz" }
+uu_grep = { path = ".." }
+
+[[bin]]
+name = "fuzz_grep"
+path = "fuzz_targets/fuzz_grep.rs"
+test = false
+doc = false

fuzz/fuzz_targets/fuzz_grep.rs

@@ -0,0 +1,189 @@
+// 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.
+// spell-checker:ignore uumain seedable
+
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use uu_grep::uumain;
+
+use rand::prelude::IndexedRandom;
+use rand::rngs::StdRng;
+use rand::{RngExt, SeedableRng};
+use std::ffi::OsString;
+
+use uufuzz::{CommandResult, compare_result, generate_and_run_uumain, run_gnu_cmd};
+
+static CMD_PATH: &str = "grep";
+
+/// Derive a 32-byte RNG seed from the libFuzzer input so that every run is a
+/// pure function of `data`. This is what makes crash artifacts reproducible:
+/// the same bytes always generate the same pattern/args/input.
+fn seed_from_data(data: &[u8]) -> StdRng {
+    let mut seed = [0u8; 32];
+    for (i, b) in data.iter().enumerate() {
+        seed[i % 32] ^= b;
+    }
+    StdRng::from_seed(seed)
+}
+
+/// Random string mixing valid UTF-8 (incl. multi-byte) and the occasional
+/// invalid byte. Driven by the caller's seeded RNG so output is deterministic.
+fn gen_random_string(rng: &mut StdRng, max_length: usize) -> String {
+    let valid_utf8: Vec<char> =
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789🔩🪛🪓⚙️🔗🧰"
+            .chars()
+            .collect();
+    let invalid_utf8 = [0xC3u8, 0x28];
+    let mut result = String::new();
+
+    for _ in 0..rng.random_range(0..=max_length) {
+        if rng.random_bool(0.9) {
+            result.push(*valid_utf8.choose(rng).unwrap());
+        } else if let Some(c) = char::from_u32(*invalid_utf8.choose(rng).unwrap() as u32) {
+            result.push(c);
+        }
+    }
+
+    result
+}
+
+/// Generate a (mostly) meaningful set of grep flags, occasionally throwing in
+/// garbage to exercise error handling.
+fn generate_grep_args(rng: &mut StdRng) -> Vec<OsString> {
+    let arg_count = rng.random_range(0..=5);
+    let mut args = Vec::new();
+
+    for _ in 0..arg_count {
+        // Small chance of an invalid argument.
+        if rng.random_bool(0.1) {
+            let len = rng.random_range(1..=10);
+            args.push(OsString::from(gen_random_string(rng, len)));
+            continue;
+        }
+
+        match rng.random_range(0..=15) {
+            0 => args.push(OsString::from("-i")), // ignore case
+            1 => args.push(OsString::from("-v")), // invert match
+            2 => args.push(OsString::from("-c")), // count
+            3 => args.push(OsString::from("-n")), // line number
+            4 => args.push(OsString::from("-o")), // only matching
+            5 => args.push(OsString::from("-w")), // word boundaries
+            6 => args.push(OsString::from("-x")), // whole line match
+            7 => args.push(OsString::from("-F")), // fixed strings
+            8 => args.push(OsString::from("-E")), // extended regexp
+            9 => args.push(OsString::from("-G")), // basic regexp
+            10 => args.push(OsString::from("--null-data")),
+            11 => args.push(OsString::from("--byte-offset")),
+            12 => {
+                // max-count
+                args.push(OsString::from("-m"));
+                args.push(OsString::from(rng.random_range(0..=5).to_string()));
+            }
+            13 => {
+                // after-context
+                args.push(OsString::from("-A"));
+                args.push(OsString::from(rng.random_range(0..=3).to_string()));
+            }
+            14 => {
+                // before-context
+                args.push(OsString::from("-B"));
+                args.push(OsString::from(rng.random_range(0..=3).to_string()));
+            }
+            15 => args.push(OsString::from("-s")), // suppress error messages
+            _ => (),
+        }
+    }
+
+    args
+}
+
+/// Build a pattern. Sometimes a literal token, sometimes a small regex made of
+/// random characters and metacharacters.
+fn generate_pattern(rng: &mut StdRng) -> String {
+    match rng.random_range(0..=3) {
+        0 => {
+            let len = rng.random_range(1..=5);
+            gen_random_string(rng, len)
+        }
+        1 => {
+            // A small alternation / anchored regex.
+            let la = rng.random_range(1..=3);
+            let a = gen_random_string(rng, la);
+            let lb = rng.random_range(1..=3);
+            let b = gen_random_string(rng, lb);
+            format!("{a}|{b}")
+        }
+        2 => {
+            let lb = rng.random_range(1..=3);
+            let base = gen_random_string(rng, lb);
+            let meta = ["*", "+", "?", ".", "^", "$", ".*", "[a-z]", "\\w"];
+            let m = meta[rng.random_range(0..meta.len())];
+            format!("{base}{m}")
+        }
+        _ => {
+            // Pick one of a few hand-written patterns that exercise common paths.
+            let canned = ["a", "^", "$", ".", ".*", "[0-9]+", "\\b", "()"];
+            canned[rng.random_range(0..canned.len())].to_string()
+        }
+    }
+}
+
+/// Generate input text with a mix of short and long lines.
+fn generate_input(rng: &mut StdRng, count: usize) -> String {
+    let mut lines = Vec::new();
+
+    for _ in 0..count {
+        if rng.random_bool(0.1) {
+            let len = rng.random_range(200..=500);
+            lines.push(gen_random_string(rng, len));
+        } else {
+            let len = rng.random_range(0..=20);
+            lines.push(gen_random_string(rng, len));
+        }
+    }
+
+    lines.join("\n")
+}
+
+fuzz_target!(|data: &[u8]| {
+    let mut rng = seed_from_data(data);
+
+    let pattern = generate_pattern(&mut rng);
+
+    // Pass the pattern through `-e` so it is never mistaken for a flag, then
+    // append the (possibly invalid) extra arguments.
+    let mut args = vec![
+        OsString::from("grep"),
+        OsString::from("-e"),
+        OsString::from(&pattern),
+    ];
+    args.extend(generate_grep_args(&mut rng));
+
+    let input = generate_input(&mut rng, 10);
+
+    let rust_result = generate_and_run_uumain(&args, uumain, Some(&input));
+    let gnu_result = match run_gnu_cmd(CMD_PATH, &args[1..], false, Some(&input)) {
+        Ok(result) => result,
+        Err(error_result) => {
+            eprintln!("Failed to run GNU command:");
+            eprintln!("Stderr: {}", error_result.stderr);
+            eprintln!("Exit Code: {}", error_result.exit_code);
+            CommandResult {
+                stdout: String::new(),
+                stderr: error_result.stderr,
+                exit_code: error_result.exit_code,
+            }
+        }
+    };
+
+    compare_result(
+        "grep",
+        &format!("{:?}", &args[1..]),
+        Some(&input),
+        &rust_result,
+        &gnu_result,
+        false, // Set to true if you want to fail on stderr diff
+    );
+});

fuzz/uufuzz/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "uufuzz"
+description = "uutils ~ 'core' uutils fuzzing library"
+repository = "https://github.com/uutils/coreutils/tree/main/fuzz/uufuzz"
+version = "0.8.0"
+edition = "2024"
+rust-version = "1.88.0"
+license = "MIT"
+
+[dependencies]
+console = "0.16.0"
+rand = { version = "0.10.1", features = ["std_rng"] }
+similar = "3.0.0"
+uucore = { version = "0.8.0", features = ["parser"] }
+tempfile = "3.15.0"
+rustix = { version = "1.1.4", features = ["stdio", "pipe"] }

fuzz/uufuzz/README.md

@@ -0,0 +1,137 @@
+# uufuzz
+
+A Rust library for **differential fuzzing** of command-line utilities. Originally designed for testing uutils coreutils against GNU coreutils, but can be used to compare any two implementations of command-line tools.
+
+Differential fuzzing is a testing technique that compares the behavior of two implementations of the same functionality using randomly generated inputs. This helps identify bugs, inconsistencies, and security vulnerabilities by finding cases where implementations diverge unexpectedly.
+
+## Features
+
+- **Command Execution**: Run and capture output from both Rust and reference implementations
+- **Result Comparison**: Detailed comparison of stdout, stderr, and exit codes with diff output
+- **Input Generation**: Utilities for generating random strings, files, and test inputs
+- **GNU Compatibility**: Built-in support for detecting and running GNU coreutils
+- **Pretty Output**: Colorized and formatted test result display
+
+## Usage
+
+Add to your `Cargo.toml`:
+
+```toml
+[dependencies]
+uufuzz = "0.1.0"
+```
+
+### Basic Example
+
+```rust
+use std::ffi::OsString;
+use uufuzz::{generate_and_run_uumain, run_gnu_cmd, compare_result};
+
+// Your utility's main function
+fn my_echo_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    // Implementation here
+    0
+}
+
+// Test against GNU implementation
+let args = vec![OsString::from("echo"), OsString::from("hello")];
+
+// Run your implementation
+let rust_result = generate_and_run_uumain(&args, my_echo_main, None);
+
+// Run GNU implementation
+let gnu_result = run_gnu_cmd("echo", &args[1..], false, None).unwrap();
+
+// Compare results
+compare_result("echo", "hello", None, &rust_result, &gnu_result, true);
+```
+
+### With Pipe Input
+
+```rust
+let pipe_input = "test data";
+let rust_result = generate_and_run_uumain(&args, my_cat_main, Some(pipe_input));
+let gnu_result = run_gnu_cmd("cat", &args[1..], false, Some(pipe_input)).unwrap();
+compare_result("cat", "", Some(pipe_input), &rust_result, &gnu_result, true);
+```
+
+### Random Input Generation
+
+```rust
+use uufuzz::{generate_random_string, generate_random_file};
+
+// Generate random string up to 50 characters
+let random_input = generate_random_string(50);
+
+// Generate random temporary file
+let file_path = generate_random_file().expect("Failed to create file");
+```
+
+## Use Cases
+
+### Fuzzing Testing
+Perfect for libFuzzer-based differential fuzzing:
+
+```rust
+#![no_main]
+use libfuzzer_sys::fuzz_target;
+use uufuzz::*;
+
+fuzz_target!(|_data: &[u8]| {
+    let args = generate_test_args();
+    let rust_result = generate_and_run_uumain(&args, my_utility_main, None);
+    let gnu_result = run_gnu_cmd("utility", &args[1..], false, None).unwrap();
+    compare_result("utility", &format!("{:?}", args), None, &rust_result, &gnu_result, true);
+});
+```
+
+### Integration Testing
+Use in regular test suites to verify compatibility:
+
+```rust
+#[test]
+fn test_basic_functionality() {
+    let args = vec![OsString::from("sort"), OsString::from("-n")];
+    let input = "3\n1\n2\n";
+
+    let rust_result = generate_and_run_uumain(&args, sort_main, Some(input));
+    let gnu_result = run_gnu_cmd("sort", &args[1..], false, Some(input)).unwrap();
+
+    assert_eq!(rust_result.stdout, gnu_result.stdout);
+    assert_eq!(rust_result.exit_code, gnu_result.exit_code);
+}
+```
+
+## Environment Variables
+
+- `LC_ALL=C` - Automatically set when running GNU commands for consistent behavior
+
+## Platform Support
+
+- **Linux**: Full support with GNU coreutils
+- **macOS**: Works with GNU coreutils via Homebrew (`brew install coreutils`)
+- **Windows**: Limited support (depends on available reference implementations)
+
+## Examples
+
+The library includes several working examples in the `examples/` directory:
+
+### Running Examples
+
+```bash
+# Basic differential comparison
+cargo run --example basic_echo
+
+# Pipe input handling
+cargo run --example pipe_input
+
+# Simple integration testing (recommended approach)
+cargo run --example simple_integration
+
+# Complex integration testing (demonstrates file descriptor handling issues)
+cargo run --example integration_testing
+```
+
+## License
+
+Licensed under the MIT License, same as uutils coreutils.

fuzz/uufuzz/examples/basic_echo.rs

@@ -0,0 +1,61 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use std::ffi::OsString;
+use uufuzz::{compare_result, generate_and_run_uumain, run_gnu_cmd};
+
+// Mock echo implementation for demonstration
+fn mock_echo_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    let args: Vec<OsString> = args.collect();
+
+    // Skip the program name (first argument)
+    for (i, arg) in args.iter().skip(1).enumerate() {
+        if i > 0 {
+            print!(" ");
+        }
+        print!("{}", arg.to_string_lossy());
+    }
+    println!();
+    0
+}
+
+fn main() {
+    println!("=== Basic uufuzz Example ===");
+
+    // Test against GNU implementation
+    let args = vec![
+        OsString::from("echo"),
+        OsString::from("hello"),
+        OsString::from("world"),
+    ];
+
+    println!("Running mock echo implementation...");
+    let rust_result = generate_and_run_uumain(&args, mock_echo_main, None);
+
+    println!("Running GNU echo...");
+    match run_gnu_cmd("echo", &args[1..], false, None) {
+        Ok(gnu_result) => {
+            println!("Comparing results...");
+            compare_result(
+                "echo",
+                "hello world",
+                None,
+                &rust_result,
+                &gnu_result,
+                false,
+            );
+        }
+        Err(error_result) => {
+            println!("Failed to run GNU echo: {}", error_result.stderr);
+            println!("This is expected if GNU coreutils is not installed");
+
+            // Show what our implementation produced
+            println!("\nOur implementation result:");
+            println!("Stdout: '{}'", rust_result.stdout);
+            println!("Stderr: '{}'", rust_result.stderr);
+            println!("Exit code: {}", rust_result.exit_code);
+        }
+    }
+}

fuzz/uufuzz/examples/fuzzing_simulation.rs

@@ -0,0 +1,163 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use rand::RngExt;
+use std::ffi::OsString;
+use uufuzz::{generate_and_run_uumain, generate_random_string, run_gnu_cmd};
+
+// Mock echo implementation with some bugs for demonstration
+fn mock_buggy_echo_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    let args: Vec<OsString> = args.collect();
+
+    let mut should_add_newline = true;
+    let mut enable_escapes = false;
+    let mut start_index = 1;
+
+    // Parse arguments (simplified)
+    for arg in args.iter().skip(1) {
+        let arg_str = arg.to_string_lossy();
+        if arg_str == "-n" {
+            should_add_newline = false;
+            start_index += 1;
+        } else if arg_str == "-e" {
+            enable_escapes = true;
+            start_index += 1;
+        } else {
+            break;
+        }
+    }
+
+    // Print arguments
+    for (i, arg) in args.iter().skip(start_index).enumerate() {
+        if i > 0 {
+            print!(" ");
+        }
+        let arg_str = arg.to_string_lossy();
+
+        if enable_escapes {
+            // Simulate a bug: incomplete escape sequence handling
+            let processed = arg_str.replace("\\n", "\n").replace("\\t", "\t");
+            print!("{}", processed);
+        } else {
+            print!("{}", arg_str);
+        }
+    }
+
+    if should_add_newline {
+        println!();
+    }
+
+    0
+}
+
+// Generate test arguments for echo command
+fn generate_echo_args() -> Vec<OsString> {
+    let mut rng = rand::rng();
+    let mut args = vec![OsString::from("echo")];
+
+    // Randomly add flags
+    if rng.random_bool(0.3) {
+        // 30% chance
+        args.push(OsString::from("-n"));
+    }
+    if rng.random_bool(0.2) {
+        // 20% chance
+        args.push(OsString::from("-e"));
+    }
+
+    // Add 1-3 random string arguments
+    let num_args = rng.random_range(1..=3);
+    for _ in 0..num_args {
+        let arg = generate_random_string(rng.random_range(1..=15));
+        args.push(OsString::from(arg));
+    }
+
+    args
+}
+
+fn main() {
+    println!("=== Fuzzing Simulation uufuzz Example ===");
+    println!("This simulates how libFuzzer would test our echo implementation");
+    println!("against GNU echo with random inputs.\n");
+
+    let num_tests = 10;
+    let mut passed = 0;
+    let mut failed = 0;
+
+    for i in 1..=num_tests {
+        println!("--- Fuzz Test {} ---", i);
+
+        let args = generate_echo_args();
+        println!(
+            "Testing with args: {:?}",
+            args.iter().map(|s| s.to_string_lossy()).collect::<Vec<_>>()
+        );
+
+        // Run our implementation
+        let rust_result = generate_and_run_uumain(&args, mock_buggy_echo_main, None);
+
+        // Run GNU implementation
+        match run_gnu_cmd("echo", &args[1..], false, None) {
+            Ok(gnu_result) => {
+                // Check if results match
+                let stdout_match = rust_result.stdout.trim() == gnu_result.stdout.trim();
+                let exit_code_match = rust_result.exit_code == gnu_result.exit_code;
+
+                if stdout_match && exit_code_match {
+                    println!("✓ PASS: Implementations match");
+                    passed += 1;
+                } else {
+                    println!("✗ FAIL: Implementations differ");
+                    failed += 1;
+
+                    // Show the difference in a controlled way (not panicking like compare_result)
+                    if !stdout_match {
+                        println!("  Stdout difference:");
+                        println!(
+                            "    Ours: '{}'",
+                            rust_result.stdout.trim().replace('\n', "\\n")
+                        );
+                        println!(
+                            "    GNU:  '{}'",
+                            gnu_result.stdout.trim().replace('\n', "\\n")
+                        );
+                    }
+                    if !exit_code_match {
+                        println!(
+                            "  Exit code difference: {} vs {}",
+                            rust_result.exit_code, gnu_result.exit_code
+                        );
+                    }
+                }
+            }
+            Err(error_result) => {
+                println!("⚠ GNU echo not available: {}", error_result.stderr);
+                println!("  Our result: '{}'", rust_result.stdout.trim());
+                // Don't count this as pass or fail
+                continue;
+            }
+        }
+
+        println!();
+    }
+
+    println!("=== Fuzzing Results ===");
+    println!("Total tests: {}", num_tests);
+    println!("Passed: {}", passed);
+    println!("Failed: {}", failed);
+
+    if failed > 0 {
+        println!(
+            "\n⚠ Found {} discrepancies! In real fuzzing, these would be investigated.",
+            failed
+        );
+        println!("This demonstrates how differential fuzzing can find bugs in implementations.");
+    } else {
+        println!("\n✓ All tests passed! The implementations appear compatible.");
+    }
+
+    println!("\nIn a real libfuzzer setup, this would run thousands of iterations");
+    println!("automatically with more sophisticated input generation.");
+}

fuzz/uufuzz/examples/integration_testing.rs

@@ -0,0 +1,236 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use std::ffi::OsString;
+use uufuzz::{generate_and_run_uumain, run_gnu_cmd};
+
+// Mock sort implementation for demonstration
+fn mock_sort_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    use std::io::{self, Read};
+
+    let args: Vec<OsString> = args.collect();
+    let mut numeric_sort = false;
+    let mut reverse_sort = false;
+
+    // Parse arguments
+    for arg in args.iter().skip(1) {
+        let arg_str = arg.to_string_lossy();
+        match arg_str.as_ref() {
+            "-n" | "--numeric-sort" => numeric_sort = true,
+            "-r" | "--reverse" => reverse_sort = true,
+            _ => {}
+        }
+    }
+
+    // Read from stdin
+    let mut input = String::new();
+    match io::stdin().read_to_string(&mut input) {
+        Ok(_) => {
+            let mut lines: Vec<&str> = input.lines().collect();
+
+            if numeric_sort {
+                // Sort numerically
+                lines.sort_by(|a, b| {
+                    let a_num: f64 = a.trim().parse().unwrap_or(0.0);
+                    let b_num: f64 = b.trim().parse().unwrap_or(0.0);
+                    a_num.partial_cmp(&b_num).unwrap()
+                });
+            } else {
+                // Sort lexically
+                lines.sort();
+            }
+
+            if reverse_sort {
+                lines.reverse();
+            }
+
+            for line in lines {
+                println!("{}", line);
+            }
+            0
+        }
+        Err(_) => {
+            eprintln!("Error reading from stdin");
+            1
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_basic_sort_functionality() {
+        println!("Testing basic sort functionality...");
+        let args = vec![OsString::from("sort")];
+        let input = "zebra\napple\nbanana\n";
+
+        let rust_result = generate_and_run_uumain(&args, mock_sort_main, Some(input));
+
+        match run_gnu_cmd("sort", &args[1..], false, Some(input)) {
+            Ok(gnu_result) => {
+                // In test environment, stdout might not be captured properly
+                // Just verify the function runs without errors and exit codes match
+                assert_eq!(
+                    rust_result.exit_code, gnu_result.exit_code,
+                    "Exit codes should match"
+                );
+                println!("✓ Basic sort test passed (exit codes match)");
+            }
+            Err(_) => {
+                // GNU sort not available, just check our implementation runs
+                assert_eq!(
+                    rust_result.exit_code, 0,
+                    "Our sort should exit successfully"
+                );
+                println!("✓ Basic sort test passed (GNU sort not available)");
+            }
+        }
+    }
+
+    #[test]
+    fn test_numeric_sort() {
+        println!("Testing numeric sort...");
+        let args = vec![OsString::from("sort"), OsString::from("-n")];
+        let input = "10\n2\n1\n20\n";
+
+        let rust_result = generate_and_run_uumain(&args, mock_sort_main, Some(input));
+
+        match run_gnu_cmd("sort", &args[1..], false, Some(input)) {
+            Ok(gnu_result) => {
+                assert_eq!(
+                    rust_result.exit_code, gnu_result.exit_code,
+                    "Exit codes should match"
+                );
+                println!("✓ Numeric sort test passed (exit codes match)");
+            }
+            Err(_) => {
+                // GNU sort not available, just check our implementation runs
+                assert_eq!(
+                    rust_result.exit_code, 0,
+                    "Our numeric sort should exit successfully"
+                );
+                println!("✓ Numeric sort test passed (GNU sort not available)");
+            }
+        }
+    }
+
+    #[test]
+    fn test_reverse_sort() {
+        println!("Testing reverse sort...");
+        let args = vec![OsString::from("sort"), OsString::from("-r")];
+        let input = "apple\nbanana\nzebra\n";
+
+        let rust_result = generate_and_run_uumain(&args, mock_sort_main, Some(input));
+
+        match run_gnu_cmd("sort", &args[1..], false, Some(input)) {
+            Ok(gnu_result) => {
+                assert_eq!(
+                    rust_result.exit_code, gnu_result.exit_code,
+                    "Exit codes should match"
+                );
+                println!("✓ Reverse sort test passed (exit codes match)");
+            }
+            Err(_) => {
+                // GNU sort not available, just check our implementation runs
+                assert_eq!(
+                    rust_result.exit_code, 0,
+                    "Our reverse sort should exit successfully"
+                );
+                println!("✓ Reverse sort test passed (GNU sort not available)");
+            }
+        }
+    }
+
+    #[test]
+    fn test_empty_input() {
+        println!("Testing empty input...");
+        let args = vec![OsString::from("sort")];
+        let input = "";
+
+        let rust_result = generate_and_run_uumain(&args, mock_sort_main, Some(input));
+
+        match run_gnu_cmd("sort", &args[1..], false, Some(input)) {
+            Ok(gnu_result) => {
+                assert_eq!(
+                    rust_result.exit_code, gnu_result.exit_code,
+                    "Exit codes should match"
+                );
+                println!("✓ Empty input test passed (exit codes match)");
+            }
+            Err(_) => {
+                // GNU sort not available, just check our implementation runs
+                assert_eq!(
+                    rust_result.exit_code, 0,
+                    "Should exit successfully with empty input"
+                );
+                println!("✓ Empty input test passed (GNU sort not available)");
+            }
+        }
+    }
+}
+
+fn main() {
+    println!("=== Integration Testing uufuzz Example ===");
+    println!("This demonstrates how to use uufuzz in regular test suites");
+    println!("to verify compatibility with reference implementations.\n");
+
+    println!("Run 'cargo test --example integration_testing' to execute the tests.");
+    println!("Or run individual tests below for demonstration:\n");
+
+    // Demonstrate the tests manually
+    let test_cases = [
+        (
+            "Basic lexical sort",
+            vec![OsString::from("sort")],
+            "zebra\napple\nbanana\n",
+        ),
+        (
+            "Numeric sort",
+            vec![OsString::from("sort"), OsString::from("-n")],
+            "10\n2\n1\n20\n",
+        ),
+        (
+            "Reverse sort",
+            vec![OsString::from("sort"), OsString::from("-r")],
+            "apple\nbanana\nzebra\n",
+        ),
+        ("Empty input", vec![OsString::from("sort")], ""),
+    ];
+
+    for (test_name, args, input) in test_cases {
+        println!("--- {} ---", test_name);
+        println!(
+            "Args: {:?}",
+            args.iter().map(|s| s.to_string_lossy()).collect::<Vec<_>>()
+        );
+        println!("Input: {:?}", input.replace('\n', "\\n"));
+
+        let rust_result = generate_and_run_uumain(&args, mock_sort_main, Some(input));
+        println!("Our output: {:?}", rust_result.stdout.replace('\n', "\\n"));
+        println!("Exit code: {}", rust_result.exit_code);
+
+        match run_gnu_cmd("sort", &args[1..], false, Some(input)) {
+            Ok(gnu_result) => {
+                println!("GNU output: {:?}", gnu_result.stdout.replace('\n', "\\n"));
+                if rust_result.stdout == gnu_result.stdout
+                    && rust_result.exit_code == gnu_result.exit_code
+                {
+                    println!("✓ Outputs match!");
+                } else {
+                    println!("✗ Outputs differ!");
+                }
+            }
+            Err(_) => {
+                println!("GNU sort not available for comparison");
+            }
+        }
+        println!();
+    }
+
+    println!("=== Example completed ===");
+    println!("In a real test suite, assertions would ensure compatibility.");
+}

fuzz/uufuzz/examples/pipe_input.rs

@@ -0,0 +1,68 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use std::ffi::OsString;
+use std::io::{self, Read};
+use uufuzz::{compare_result, generate_and_run_uumain, run_gnu_cmd};
+
+// Mock cat implementation for demonstration
+fn mock_cat_main(args: std::vec::IntoIter<OsString>) -> i32 {
+    let _args: Vec<OsString> = args.collect();
+
+    // Read from stdin and write to stdout
+    let mut input = String::new();
+    match io::stdin().read_to_string(&mut input) {
+        Ok(_) => {
+            print!("{}", input);
+            0
+        }
+        Err(_) => {
+            eprintln!("Error reading from stdin");
+            1
+        }
+    }
+}
+
+fn main() {
+    println!("=== Pipe Input uufuzz Example ===");
+
+    let args = vec![OsString::from("cat")];
+    let pipe_input = "Hello from pipe!\nThis is line 2.\nAnd line 3.";
+
+    println!("Running mock cat implementation with pipe input...");
+    let rust_result = generate_and_run_uumain(&args, mock_cat_main, Some(pipe_input));
+
+    println!("Running GNU cat with pipe input...");
+    match run_gnu_cmd("cat", &args[1..], false, Some(pipe_input)) {
+        Ok(gnu_result) => {
+            println!("Comparing results...");
+            compare_result(
+                "cat",
+                "",
+                Some(pipe_input),
+                &rust_result,
+                &gnu_result,
+                false,
+            );
+        }
+        Err(error_result) => {
+            println!("Failed to run GNU cat: {}", error_result.stderr);
+            println!("This is expected if GNU coreutils is not installed");
+
+            // Show what our implementation produced
+            println!("\nOur implementation result:");
+            println!("Stdout: '{}'", rust_result.stdout);
+            println!("Stderr: '{}'", rust_result.stderr);
+            println!("Exit code: {}", rust_result.exit_code);
+
+            // Verify our mock implementation works
+            if rust_result.stdout.trim() == pipe_input.trim() {
+                println!("✓ Our mock cat implementation correctly echoed the pipe input");
+            } else {
+                println!("✗ Our mock cat implementation failed to echo the pipe input correctly");
+            }
+        }
+    }
+}