CLI Tool Capstone

Build logscan, a tool that searches log files: logscan error app.log, logscan --level warn --since 24h scan app.log out/, logscan stats app.log. Every flag you add by hand with std::env::args() is a string match, a parse, a help string, and a bug waiting to happen. clap's derive API turns the CLI's grammar into the type system: one struct per argument group, one enum per subcommand, and the parser, validation, and --help output all generate from it.

use clap::{Parser, Subcommand, ValueEnum};

#[derive(Parser)]
#[command(name = "logscan", version, about = "Search and summarize log files")]
struct Cli {
    /// Level threshold to report
    #[arg(long, value_enum, default_value_t = Level::Info)]
    level: Level,
    #[command(subcommand)]
    command: Command,
}

#[derive(ValueEnum, Clone, Copy, Debug, PartialEq)]
enum Level { Error, Warn, Info, Debug }

#[derive(Subcommand)]
enum Command {
    /// Search files for lines at or above the level
    Scan {
        /// Files to search; omit to read stdin
        files: Vec<std::path::PathBuf>,
        /// Case-insensitive substring filter
        #[arg(long)]
        contains: Option<String>,
    },
    /// Print per-level counts for a file
    Stats { file: std::path::PathBuf },
}

fn main() -> anyhow::Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Command::Scan { files, contains } => run_scan(cli.level, files, contains.as_deref()),
        Command::Stats { file } => run_stats(cli.level, file),
    }
}

Read the decisions, because interviewers ask why each one exists. Level is a ValueEnum, not a string: clap validates --level error at the parse boundary and the compiler guarantees no other values exist inside run_scan. PathBuf, not String, for file arguments — the OS hands you paths that may not be valid UTF-8, and PathBuf is the type that admits them. Vec<PathBuf> with no required attribute makes zero or many files legal in one field, and clap reads stdin when the list is empty (your code decides; clap only parses). contains: Option<String> distinguishes flag absent from flag present with a value — a distinction raw args() matching gets wrong constantly. #[command(version, about)] wires --version and the about line from Cargo.toml metadata into --help for free.

Cli::parse() is the boundary that earns its keep: on a bad flag it prints a usage error and exits with code 2 before your main logic exists, so run_scan can assume a well-formed world. Note what main returns: anyhow::Result<()> — in a binary crate, anyhow is the right error type because there is exactly one consumer (the user at the terminal) and context over a typed chain beats exhaustive matching at top level. The typed story belongs inside the library, and the next chapter builds it.

Tests belong next to the grammar while it is still cheap. Unit-test the parser by constructing argv explicitly:

#[cfg(test)]
mod tests {
    use super::*;
    use clap::CommandFactory;

    #[test]
    fn cli_definition_is_consistent() {
        Cli::command().debug_assert();   // arg ids, groups, conflicts
    }

    #[test]
    fn parses_scan_with_level_and_filter() {
        let cli = Cli::try_parse_from([
            "logscan", "--level", "warn", "scan", "a.log", "b.log", "--contains", "timeout",
        ]).unwrap();
        assert_eq!(cli.level, Level::Warn);
        match cli.command {
            Command::Scan { files, contains } => {
                assert_eq!(files.len(), 2);
                assert_eq!(contains.as_deref(), Some("timeout"));
            }
            _ => panic!("expected Scan"),
        }
    }
}

Cli::command().debug_assert() is the sleeper hit: it verifies the entire derived definition (unique ids, valid conflicts, well-formed groups) in one test you never have to update. try_parse_from takes any iterator of strings, so parser tests are pure functions — no process-global state, no subprocess. That property is what the Async and Concurrency Interview Drills topic predicted about good boundaries: parse at the edge, then pass typed values inward, and the core becomes trivially testable — which is exactly where the iterators go.

The scan core must handle a 2 GB log without loading it into memory, filter lines by level and substring, and report both kinds of failure correctly: an unreadable file is an IO problem, a malformed line is a parse problem. Two mechanisms do the work: BufRead lines as an iterator, and a custom error enum that keeps the two failure families distinct.

Start with the line source. File::open yields a File, which implements Read; wrapping it in BufRead's BufReader adds an 8 KB buffer so each next_line() is a cheap memcpy instead of a syscall. Then treat lines as a stream:

use std::fs::File;
use std::io::{self, BufRead, BufReader};
use std::path::Path;

fn scan_file(path: &Path) -> Result<Vec<ScanHit>, ScanError> {
    let file = File::open(path)?;                       // IO error, propagated
    let reader = BufReader::new(file);
    let hits = reader
        .lines()
        .enumerate()
        .map(|(i, line)| (i + 1, line?))               // per-line IO error → ScanError
        .filter_map(|(lineno, line)| match parse_line(&line) {
            Ok(entry) if entry.level >= threshold => Some(Ok(ScanHit { lineno, entry })),
            Ok(_) => None,
            Err(cause) => Some(Err(ScanError::Parse { source_line: lineno, cause })),
        })
        .collect::<Result<Vec<_>, _>>()?;               // stop at first parse error
    Ok(hits)
}

Two adapter details worth narrating. lines() yields io::Result<String>, so the line? inside map converts a mid-file read failure into your error type instead of silently truncating the stream — a silent truncation is the bug most people ship first. And collect::<Result<Vec<_>, _>>() is the idiomatic "any error aborts the pipeline" move: the iterator already threads Result through, and collect collapses it. For a tool that should count bad lines instead of dying, swap the collect for a fold that tallies Errs — same stream, different policy. Note the memory profile: one 8 KB buffer plus the hits you chose to keep; a million-line file never materializes as one Vec<String>.

Now the error type. Inside the library crate, thiserror derives the Display and From plumbing for an enum whose variants are your failure taxonomy:

use thiserror::Error;

#[derive(Error, Debug)]
pub enum ScanError {
    #[error("cannot open {path}: {source}")]
    Open {
        path: std::path::PathBuf,
        #[source]
        source: io::Error,
    },
    #[error("read error in {path} after line {line}: {source}")]
    Read {
        path: std::path::PathBuf,
        line: usize,
        #[source]
        source: io::Error,
    },
    #[error("unparseable entry at {path}:{source_line}: {cause}")]
    Parse {
        path: std::path::PathBuf,
        source_line: usize,
        cause: LogParseError,
    },
}

The design rules this encodes, which is what an interviewer actually probes. First, variants separate the failure domains: Open/Read mean the filesystem failed (permissions, disk, deleted file); Parse means the input was bad — and only the caller knows whether that aborts the run or increments a counter. Collapsing both into Box<dyn Error> or one String loses exactly the information your main needs to choose an exit code. Second, #[source] preserves the underlying io::Error for {:?} chains while #[error(...)] gives users a one-line message that names the file and line — parse errors must tell the user where to look in their data, which is why source_line is a field, not a log message. Third, #[from] on the variants you want implicit conversion for makes every ? in the streaming code above just work. The binary's main then matches once: Parse prints the location and exits 1, Open/Read exits 1 with the OS message, Ok exits 0 — the error enum is the exit-code table. The full thiserror/anyhow rationale — and why the split flips between library and binary crates — is covered in Anyhow and Thiserror; this capstone applies it to a real taxonomy. The last piece before shipping is proving the whole pipeline from the outside, covered next.

Unit tests cover parse_line and the iterator pipeline. What they cannot prove is the contract a user actually experiences: exit codes, stderr messages, --help, stdin handling. That is the job of integration tests that run the built binary as a subprocess — the assert_cmd + predicates combination that most polished Rust CLIs ship.

use assert_cmd::Command;
use predicates::prelude::*;

#[test]
fn scan_reports_matches_and_exits_zero() {
    Command::cargo_bin("logscan").unwrap()
        .args(["--level", "error", "scan", "tests/fixtures/sample.log"])
        .assert()
        .success()
        .stdout(predicate::str::contains("app.log:14").from_env());
}

#[test]
fn missing_file_exits_one_with_context() {
    Command::cargo_bin("logscan").unwrap()
        .args(["scan", "no/such/file.log"])
        .assert()
        .failure()
        .code(1)
        .stderr(predicate::str::contains("cannot open")
                 .and(predicate::str::contains("no/such/file.log")));
}

#[test]
fn bad_level_is_a_usage_error() {
    Command::cargo_bin("logscan").unwrap()
        .args(["--level", "fatal", "scan", "x.log"])
        .assert()
        .failure()
        .code(2)                       // clap's usage-exit code, not yours
        .stderr(predicate::str::contains("possible values: error, warn, info, debug"));
}

Command::cargo_bin builds the binary through cargo and spawns it; predicates turns assertions into composable matchers. Note what each test asserts and what it refuses to assert: the third test does not call into your scan code at all — it proves that clap rejects fatal before your main logic is reachable, pinning the boundary between the generated parser and your hand-written core. That is the layering paying for itself in the test suite: parser behavior is proven by construction (debug_assert, try_parse_from), behavior users see is proven from outside, and the core is proven by unit tests with direct calls. Three properties make this suite worth its minutes. It is black-box: exactly what a user types and sees, including clap's own messages — which is how you notice that --level fatal exits 2 with the possible-values list for free, something no unit test of your own code could verify. It is fixture-driven: tests/fixtures/sample.log is a checked-in 30-line log with known hits, one malformed line, and a CRLF line — a miniature of every input class, so a regression in lines() handling shows up as a named failing test, not a user report. And it forces the exit-code discipline from the previous chapter into a written contract: 0 success, 1 runtime error, 2 usage error.

Before tagging, the checklist — the production baseline from Production Crate Baseline now pays off directly: what began as four commands in a generic CI template is now four gates standing in front of a specific artifact that users will download, and each one maps to a failure you have already seen happen in this project's own history. Run them in this order, cheapest first, so the fastest feedback comes earliest:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features              # unit + integration + doc tests
cargo audit                            # advisories in Cargo.lock
cargo dist plan                        # what the tag will publish

Then the release itself, automated by cargo-dist (configured in that same baseline topic): a v0.1.0 tag triggers the workflow, which cross-builds logscan for your target list, archives each with checksums, and drafts the GitHub Release with install instructions. Two finishing touches that separate a repo from a tool: shell completions generated by clap (Cli::command().generate_completions_to into an included asset or a completions hidden subcommand) and a --json output mode on stats so the tool composes in pipelines.

How to present this capstone in an interview: walk the architecture as a funnel — clap parses strings into typed values once, the library core consumes only typed values and returns Result<_, ScanError>, and main alone decides exit codes. Then name the two tests that prove each boundary (debug_assert for the grammar, missing_file_exits_one_with_context for the error contract). That framing shows a reviewer's instinct — boundaries tested from outside, errors typed inside — which is the real deliverable. The capstone that exercises the same instincts under threads and channels is Concurrent Service Capstone.