Intermediate

use clap::{Parser, Subcommand};          // => Import both Parser and Subcommand derives
 
#[derive(Parser)]
#[command(name = "my-checker", version = "0.1.0", about = "File validation tool")]
struct Cli {
    #[command(subcommand)]               // => This field holds the chosen subcommand
    command: Commands,                   // => Commands is the enum below
}
 
#[derive(Subcommand)]                    // => Generates subcommand parsing for this enum
enum Commands {
    #[command(about = "Check files for violations")]
    Check {                              // => Struct-like variant: carries own arguments
        #[arg(long, default_value = ".")]
        path: String,                    // => --path argument specific to Check
        #[arg(long)]
        strict: bool,                    // => --strict flag specific to Check
    },
    #[command(about = "Format a report")]
    Report {
        #[arg(long, default_value = "text")]
        format: String,                  // => --format argument specific to Report
    },
}
 
fn main() {
    let cli = Cli::parse();              // => Parse arguments, exit on error
 
    match cli.command {                  // => Dispatch on which subcommand was chosen
        Commands::Check { path, strict } => {
                                         // => Destructure the struct variant
            println!("Checking: {}", path);
            if strict {
                println!("Strict mode enabled");
            }
                                         // => Running: ./my-checker check --path src/ --strict
                                         // => Output: Checking: src/
                                         // =>         Strict mode enabled
        }
        Commands::Report { format } => {
            println!("Reporting in {} format", format);
                                         // => Running: ./my-checker report --format json
                                         // => Output: Reporting in json format
        }
    }
}

use clap::{Parser, Subcommand};
 
#[derive(Parser)]
#[command(name = "my-tool")]
struct Cli {
    #[command(subcommand)]
    command: TopLevel,
}
 
#[derive(Subcommand)]
enum TopLevel {
    #[command(about = "Document-related commands")]
    Docs {
        #[command(subcommand)]           // => Nested: Docs contains another subcommand
        command: DocsCommand,
    },
    #[command(about = "Run all checks")]
    Check,
}
 
#[derive(Subcommand)]
enum DocsCommand {
    #[command(about = "Validate documents")]
    Validate {
        #[arg(long, default_value = "docs/")]
        path: String,
    },
    #[command(about = "Check document links")]
    Links,
}
 
fn main() {
    let cli = Cli::parse();
 
    match cli.command {                  // => First level dispatch
        TopLevel::Docs { command } => {  // => Docs carries a nested DocsCommand
            match command {              // => Second level dispatch
                DocsCommand::Validate { path } => {
                    println!("Validating docs at: {}", path);
                                         // => Running: ./my-tool docs validate --path docs/
                                         // => Output: Validating docs at: docs/
                }
                DocsCommand::Links => {
                    println!("Checking document links");
                }
            }
        }
        TopLevel::Check => {
            println!("Running all checks");
        }
    }
}

use clap::{Parser, Subcommand};
 
#[derive(Parser)]
#[command(name = "my-checker")]
struct Cli {
    #[arg(long, global = true, help = "Enable verbose output")]
    verbose: bool,                       // => Global: available to all subcommands
                                         // => --verbose works before or after subcommand
 
    #[arg(long, global = true, value_enum, default_value = "text")]
    output: OutputFormat,                // => Global output format flag
 
    #[command(subcommand)]
    command: Commands,
}
 
#[derive(clap::ValueEnum, Clone, Debug)]
enum OutputFormat {                      // => ValueEnum: clap parses string to enum variant
    Text,
    Json,
    Markdown,
}
 
#[derive(Subcommand)]
enum Commands {
    Check { #[arg(long)] path: String },
    Report,
}
 
fn main() {
    let cli = Cli::parse();
 
    if cli.verbose {                     // => Access global flag at top level
        eprintln!("[verbose] command={:?} format={:?}", cli.command, cli.output);
    }
 
    match cli.command {
        Commands::Check { path } => {
            println!("Checking {} with format {:?}", path, cli.output);
                                         // => cli.output available inside subcommand handler
        }
        Commands::Report => {
            println!("Reporting with format {:?}", cli.output);
        }
    }
}

fn main() {
    let raw = "  --verbose, --quiet, --format=json  ";
 
    // Trimming whitespace
    let trimmed = raw.trim();            // => Removes leading/trailing whitespace
                                         // => trimmed: "--verbose, --quiet, --format=json"
    println!("{:?}", trimmed);
 
    // Splitting
    let parts: Vec<&str> = trimmed.split(", ").collect();
                                         // => .split() returns iterator of &str slices
                                         // => parts: ["--verbose", "--quiet", "--format=json"]
    println!("{:?}", parts);
 
    // Containment checks
    println!("{}", trimmed.contains("json"));    // => true
    println!("{}", trimmed.starts_with("--"));   // => true
    println!("{}", trimmed.ends_with("json"));   // => true
 
    // Case conversion
    let filename = "README.MD";
    println!("{}", filename.to_lowercase());     // => readme.md
    println!("{}", filename.to_uppercase());     // => README.MD
 
    // Replacement
    let snake = "my_variable_name";
    let kebab = snake.replace('_', "-");         // => "my-variable-name" (new String)
    println!("{}", kebab);
 
    // Lines iterator
    let content = "line one\nline two\nline three";
    let count = content.lines().count();         // => 3 (splits on \n and \r\n)
    println!("Lines: {}", count);
 
    // Parsing a key=value flag
    let flag = "--format=json";
    if let Some(value) = flag.strip_prefix("--format=") {
                                         // => .strip_prefix() returns Option<&str>
                                         // => value: "json" if prefix matches
        println!("Format: {}", value);   // => Output: Format: json
    }
 
    // Checking if all chars match a predicate
    let name = "my-tool-123";
    let is_valid = name.chars().all(|c| c.is_alphanumeric() || c == '-');
                                         // => .chars() iterates Unicode scalar values
                                         // => .all() returns true if all chars pass
    println!("Valid: {}", is_valid);     // => Output: Valid: true
}

use std::io::Write;
 
fn main() {
    // Basic formatting
    let name = "checker";
    let count = 42u32;
    let ratio = 0.856_f64;
 
    println!("Tool: {}", name);          // => Display: Tool: checker
    println!("Debug: {:?}", name);       // => Debug: "checker" (with quotes for str)
    println!("Count: {:?}", count);      // => Debug: 42
 
    // Width and alignment
    println!("{:<20} {:>5}", "file.rs", 3);
                                         // => Left-align 20, right-align 5
                                         // => Output: file.rs              3
    println!("{:0>4}", 7);              // => Pad with zeros: "0007"
    println!("{:0>4}", 42);             // => "0042"
 
    // Float precision
    println!("{:.2}", ratio);            // => 2 decimal places: 0.86
    println!("{:.4}", ratio);            // => 4 decimal places: 0.8560
 
    // Named arguments
    println!("{name} processed {count} files with {ratio:.1}% success",
        name = name, count = count, ratio = ratio * 100.0);
                                         // => checker processed 42 files with 85.6% success
 
    // eprintln! to stderr
    eprintln!("Error: {} not found", "config.toml");
                                         // => Writes to stderr (does not appear in stdout pipe)
 
    // write! to a buffer (useful for testing — Example 50)
    let mut buffer: Vec<u8> = Vec::new();
    write!(buffer, "Header: {}\n", name).unwrap();
                                         // => Writes formatted string to Vec<u8> buffer
                                         // => .unwrap() here: Vec<u8>::write never fails
 
    let text = String::from_utf8(buffer).unwrap();
    println!("Buffer: {:?}", text);      // => Output: Buffer: "Header: checker\n"
 
    // Conditional formatting in a report row
    let files = vec![
        ("main.rs", 0u32, true),
        ("bad_name.rs", 3, false),
        ("utils.rs", 1, false),
    ];
 
    println!("{:<20} {:>6} {}", "File", "Errors", "Status");
    println!("{}", "-".repeat(35));      // => Separator line
 
    for (file, errors, ok) in &files {
        let status = if *ok { "PASS" } else { "FAIL" };
        println!("{:<20} {:>6} {}", file, errors, status);
    }
    // Output:
    // File                 Errors Status
    // -----------------------------------
    // main.rs                   0 PASS
    // bad_name.rs               3 FAIL
    // utils.rs                  1 FAIL
}

use std::path::{Path, PathBuf};
 
fn main() {
    // Building paths with PathBuf
    let mut config_dir = PathBuf::from("/home/user");
                                         // => config_dir: PathBuf owning "/home/user"
    config_dir.push(".config");          // => Appends component: "/home/user/.config"
    config_dir.push("my-tool");          // => "/home/user/.config/my-tool"
 
    println!("{}", config_dir.display());// => .display() for human-readable output
                                         // => Output: /home/user/.config/my-tool
 
    // .join() creates a new PathBuf (does not mutate)
    let config_file = config_dir.join("config.toml");
                                         // => New PathBuf: "/home/user/.config/my-tool/config.toml"
    println!("{}", config_file.display());
 
    // Inspecting path components
    println!("{:?}", config_file.extension()); // => Some("toml")
    println!("{:?}", config_file.file_name()); // => Some("config.toml")
    println!("{:?}", config_file.file_stem()); // => Some("config")
    println!("{:?}", config_file.parent());    // => Some("/home/user/.config/my-tool")
 
    // Existence checks (filesystem calls)
    let src = Path::new("src");
    println!("exists: {}", src.exists());  // => true if ./src directory exists
    println!("is_dir: {}", src.is_dir());  // => true if it's a directory
    println!("is_file: {}", src.is_file());// => false (it's a directory)
 
    // Functions taking &Path (accepts PathBuf via Deref coercion)
    describe_path(&config_file);          // => PathBuf coerces to &Path automatically
    describe_path(Path::new("main.rs")); // => &Path directly
 
    // Converting between PathBuf, &Path, and strings
    let path_str: &str = config_dir.to_str().unwrap_or("");
                                         // => to_str() returns Option<&str>
                                         // => None on non-UTF-8 paths (Unix can have them)
    let path_string: String = config_dir.to_string_lossy().into_owned();
                                         // => Lossy: replaces invalid UTF-8 with U+FFFD
                                         // => Safe alternative to to_str().unwrap()
}
 
fn describe_path(path: &Path) {          // => Takes &Path: accepts &PathBuf and Path::new(...)
    if path.exists() {
        println!("{}: exists", path.display());
    } else {
        println!("{}: not found", path.display());
    }
}

use std::fs::{self, File};
use std::io::{BufRead, BufReader};
 
fn main() -> Result<(), Box<dyn std::error::Error>> {
                                         // => Box<dyn Error>: accepts any error type
                                         // => Useful for main() before adding anyhow
 
    // Read entire file to String (simple, works for small files)
    let content = fs::read_to_string("Cargo.toml")?;
                                         // => Returns String with entire file content
                                         // => ? propagates io::Error if file missing
 
    println!("File size: {} bytes", content.len());
    println!("First 50 chars: {}", &content[..50.min(content.len())]);
 
    // Count lines and non-empty lines
    let line_count = content.lines().count();
    let non_empty = content.lines().filter(|l| !l.trim().is_empty()).count();
    println!("Lines: {} ({} non-empty)", line_count, non_empty);
 
    // Read a file that might not exist
    match fs::read_to_string("optional.toml") {
        Ok(s)  => println!("Optional config: {} bytes", s.len()),
        Err(e) => println!("No optional config: {}", e),
                                         // => io::ErrorKind::NotFound if missing
    }
 
    // BufReader: line-by-line for large files
    let file = File::open("Cargo.toml")?;// => Open file handle (does not read content)
    let reader = BufReader::new(file);    // => Wrap with buffered reader for efficiency
 
    let mut line_num = 0u32;
    for line in reader.lines() {          // => .lines() returns iterator of Result<String>
        let line = line?;                 // => Unwrap Result<String> or propagate error
        line_num += 1;
        if line.starts_with('[') {        // => Section headers in TOML start with [
            println!("Section at line {}: {}", line_num, line);
        }
    }
 
    Ok(())
}

use std::fs::{self, File};
use std::io::{BufWriter, Write};
 
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Write entire content at once (simple, overwrites if exists)
    let report = "File: main.rs\nErrors: 0\nStatus: PASS\n";
    fs::write("report.txt", report)?;    // => Creates or overwrites report.txt
                                         // => ? propagates io::Error
 
    println!("Wrote report.txt");
 
    // Write with BufWriter for streaming/formatted output
    let file = File::create("detailed-report.txt")?;
                                         // => File::create overwrites or creates
    let mut writer = BufWriter::new(file);// => Wrap for buffered writes (fewer syscalls)
 
    writeln!(writer, "=== Validation Report ===")?;
                                         // => writeln! adds newline, ? propagates error
    writeln!(writer, "Date: 2025-12-30")?;
 
    let files = vec![
        ("main.rs", 0u32, "PASS"),
        ("bad_name.rs", 3, "FAIL"),
    ];
 
    for (name, errors, status) in &files {
        writeln!(writer, "{:<20} {:>4} errors  [{}]", name, errors, status)?;
    }
 
    writer.flush()?;                     // => BufWriter buffers: flush ensures write to disk
    println!("Wrote detailed-report.txt");
 
    // Write to stdout with BufWriter (faster for large outputs)
    let stdout = std::io::stdout();
    let mut out = BufWriter::new(stdout.lock());
                                         // => .lock() ensures exclusive access
    writeln!(out, "Summary: {} files checked", files.len())?;
 
    Ok(())
}

use walkdir::{DirEntry, WalkDir};
 
fn is_hidden(entry: &DirEntry) -> bool { // => Check if entry name starts with dot
    entry.file_name()
         .to_str()
         .map(|s| s.starts_with('.'))    // => to_str() returns Option<&str>
         .unwrap_or(false)               // => Treat non-UTF-8 names as not hidden
}
 
fn main() {
    // Walk the current directory recursively
    let walker = WalkDir::new(".")        // => Start walking from current directory
        .min_depth(1)                     // => Skip the root directory itself
        .into_iter();                     // => Convert to iterator
 
    let rust_files: Vec<_> = walker
        .filter_entry(|e| !is_hidden(e)) // => Skip hidden directories (pruning)
                                          // => filter_entry prunes entire subtrees
        .filter_map(|e| e.ok())           // => Skip entries with permission errors
        .filter(|e| {
            e.file_type().is_file()       // => Only regular files (not directories)
                && e.path()
                   .extension()
                   .map(|ext| ext == "rs")// => Only .rs files
                   .unwrap_or(false)
        })
        .collect();
 
    println!("Found {} Rust files", rust_files.len());
 
    for entry in &rust_files {
        println!("  {}", entry.path().display());
                                          // => Print each file path
    }
 
    // Walk with depth limit
    let shallow = WalkDir::new(".")
        .max_depth(2)                     // => At most 2 levels deep
        .into_iter()
        .filter_map(|e| e.ok())
        .filter(|e| e.file_type().is_file());
 
    let shallow_count = shallow.count();
    println!("Shallow files (depth <= 2): {}", shallow_count);
}

use ignore::WalkBuilder;
 
fn main() {
    // Walk respecting .gitignore and hidden file rules
    let walker = WalkBuilder::new(".")   // => Start from current directory
        .hidden(true)                    // => true: skip hidden files/dirs (default)
        .gitignore(true)                 // => true: respect .gitignore (default)
        .build();                        // => Build the walker
 
    let mut rs_count = 0u32;
    let mut total_count = 0u32;
 
    for result in walker {
        match result {
            Ok(entry) => {
                total_count += 1;
                if entry.path().extension().map(|e| e == "rs").unwrap_or(false) {
                    rs_count += 1;
                    println!("{}", entry.path().display());
                }
            }
            Err(e) => eprintln!("Error: {}", e),
                                         // => Permission denied or similar
        }
    }
 
    println!("{} Rust files out of {} total", rs_count, total_count);
 
    // Disable gitignore to walk ALL files (useful for checking ignore rules themselves)
    let full_walker = WalkBuilder::new(".")
        .hidden(false)                   // => false: include hidden files
        .gitignore(false)                // => false: ignore .gitignore rules
        .ignore(false)                   // => false: ignore .ignore files too
        .build();
 
    let full_count = full_walker.filter_map(|e| e.ok()).count();
    println!("Total including hidden/ignored: {}", full_count);
}

use regex::Regex;
 
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Compile regex (expensive: do this once, not per file/line)
    let kebab_re = Regex::new(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")?;
                                         // => r"...": raw string, backslashes not escaped
                                         // => ^: start, $: end, anchors the whole string
                                         // => Returns Result<Regex, Error>
 
    // .is_match(): check if string matches the pattern
    println!("{}", kebab_re.is_match("my-file-name"));  // => true
    println!("{}", kebab_re.is_match("my_file_name"));  // => false (underscore)
    println!("{}", kebab_re.is_match("MyFileName"));    // => false (uppercase)
 
    // .find(): locate first match within a string
    let line = "See function my_function() on line 42";
    let word_re = Regex::new(r"[a-z_]+")?;// => Match identifier-like words
 
    if let Some(m) = word_re.find(line) { // => Returns Option<Match>
        println!("First match: {} at [{}, {}]", m.as_str(), m.start(), m.end());
                                         // => First match: See at [0, 3]
    }
 
    // .captures(): extract named or numbered groups
    let version_re = Regex::new(r"(\d+)\.(\d+)\.(\d+)")?;
                                         // => Capture groups: (major).(minor).(patch)
 
    let ver_str = "clap 4.6.1 — argument parser";
    if let Some(caps) = version_re.captures(ver_str) {
        println!("Full: {}", &caps[0]);   // => caps[0]: entire match "4.6.1"
        println!("Major: {}", &caps[1]);  // => caps[1]: first group "4"
        println!("Minor: {}", &caps[2]);  // => caps[2]: second group "6"
        println!("Patch: {}", &caps[3]);  // => caps[3]: third group "1"
    }
 
    // Named captures
    let named_re = Regex::new(r"(?P<name>[a-z_]+)\s*=\s*(?P<value>.+)")?;
                                         // => (?P<name>...) syntax for named groups
 
    let config_line = "max_errors = 100";
    if let Some(caps) = named_re.captures(config_line) {
        println!("Key: {}", caps.name("name").unwrap().as_str());
                                         // => Key: max_errors
        println!("Val: {}", caps.name("value").unwrap().as_str());
                                         // => Val: 100
    }
 
    Ok(())
}

use std::sync::LazyLock;
use regex::Regex;
 
// Global compiled regex: initialized once on first use, reused on every call
static KEBAB_RE: LazyLock<Regex> = LazyLock::new(|| {
                                         // => LazyLock::new takes a closure
                                         // => Closure called exactly once on first access
    Regex::new(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z0-9]+)?$")
        .expect("KEBAB_RE is a valid regex")
                                         // => .expect(): if this fails, the program has a bug
                                         // => Regex literal errors are programming errors,
                                         // => not user errors — unwrap/expect is appropriate
});
 
static VERSION_RE: LazyLock<Regex> = LazyLock::new(|| {
    Regex::new(r"(?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)")
        .expect("VERSION_RE is a valid regex")
});
 
fn is_valid_filename(name: &str) -> bool {
    KEBAB_RE.is_match(name)              // => Accesses global; lazy-initialized on first call
                                         // => Subsequent calls reuse the compiled Regex
}
 
fn main() {
    let filenames = [
        "my-checker.rs",
        "bad_name.rs",
        "README.md",
        "main.rs",
        "utils-v2.rs",
    ];
 
    for name in &filenames {
        println!("{}: {}", name, if is_valid_filename(name) { "ok" } else { "bad" });
    }
    // Output:
    // my-checker.rs: ok
    // bad_name.rs: bad
    // README.md: bad
    // main.rs: ok
    // utils-v2.rs: ok
 
    // VERSION_RE also lazy: compiled on first access here
    let version_str = "Using clap 4.6.1 for argument parsing";
    if let Some(caps) = VERSION_RE.captures(version_str) {
        println!("Version: {}.{}.{}",
            caps.name("major").unwrap().as_str(),
            caps.name("minor").unwrap().as_str(),
            caps.name("patch").unwrap().as_str());
                                         // => Output: Version: 4.6.1
    }
}

use std::sync::OnceLock;
use std::collections::HashMap;
use regex::Regex;
 
// OnceLock holds a HashMap of compiled patterns
// The HashMap is initialized on first call with whatever patterns are needed
static PATTERN_CACHE: OnceLock<HashMap<&'static str, Regex>> = OnceLock::new();
 
fn get_patterns() -> &'static HashMap<&'static str, Regex> {
    PATTERN_CACHE.get_or_init(|| {       // => Closure runs only on first call
                                          // => Returns reference on all subsequent calls
        let mut map = HashMap::new();
        map.insert(
            "kebab",
            Regex::new(r"^[a-z][a-z0-9-]*$").expect("valid"),
        );
        map.insert(
            "version",
            Regex::new(r"^\d+\.\d+\.\d+$").expect("valid"),
        );
        map                              // => HashMap moved into OnceLock
    })
}
 
fn main() {
    let patterns = get_patterns();       // => First call: initializes the HashMap
    let patterns2 = get_patterns();      // => Second call: returns same reference
 
    let test_names = [
        ("my-tool", "kebab"),
        ("MyTool", "kebab"),
        ("1.2.3", "version"),
        ("1.2", "version"),
    ];
 
    for (name, pattern_key) in &test_names {
        if let Some(re) = patterns.get(pattern_key) {
                                         // => Look up compiled Regex by name
            println!("{} ~ {}: {}", name, pattern_key, re.is_match(name));
        }
    }
    // Output:
    // my-tool ~ kebab: true
    // MyTool ~ kebab: false
    // 1.2.3 ~ version: true
    // 1.2 ~ version: false
 
    // OnceLock without a static: supply a value externally (different use case)
    let once: OnceLock<String> = OnceLock::new();
    let value = once.get_or_init(|| String::from("initialized once"));
    println!("{}", value);               // => initialized once
    let value2 = once.get_or_init(|| String::from("ignored"));
    println!("{}", value2);              // => initialized once (second init ignored)
}

use anyhow::{anyhow, bail, ensure, Context, Result};
use std::fs;
use std::path::Path;
 
fn main() -> Result<()> {               // => anyhow::Result<()>: accepts any error type
                                         // => Returns Ok(()) on success or Err(anyhow::Error)
 
    // anyhow! creates an error from a string
    let name = "";
    if name.is_empty() {
        return Err(anyhow!("tool name cannot be empty"));
                                         // => Creates anyhow::Error from the string
                                         // => Exits main with that error message
    }
 
    // bail! is early return with anyhow::Error (same as return Err(anyhow!(...)))
    let count: i32 = -1;
    if count < 0 {
        bail!("count must be non-negative, got {}", count);
                                         // => bail! = return Err(anyhow!("..."))
                                         // => Exits with formatted error message
    }
 
    // ensure! is assertion style: ensure!(condition, "error if false")
    let path = Path::new("Cargo.toml");
    ensure!(path.exists(), "required file {:?} not found", path);
                                         // => If path doesn't exist: bail with the message
                                         // => If it exists: continue
 
    // .context() wraps any error with additional information
    let content = fs::read_to_string("Cargo.toml")
        .context("failed to read Cargo.toml")?;
                                         // => If read fails: error becomes
                                         // =>   "failed to read Cargo.toml: No such file..."
                                         // => User sees both the context and the underlying cause
 
    println!("Read {} bytes from Cargo.toml", content.len());
 
    // .with_context() uses a closure (for deferred formatting)
    let result = validate_content(&content)
        .with_context(|| format!("validation failed for {}", "Cargo.toml"))?;
                                         // => Closure only called if validate_content errors
                                         // => Avoids formatting cost when no error
 
    println!("Validation: {}", result);
    Ok(())
}
 
fn validate_content(content: &str) -> Result<String> {
    ensure!(!content.is_empty(), "content is empty");
    ensure!(content.contains("[package]"), "missing [package] section");
    Ok(String::from("content is valid"))
}

use anyhow::{Context, Result};
use std::fs;
use std::path::Path;
 
fn run_validation(project_dir: &Path) -> Result<()> {
    let config = load_config(project_dir)
        .context("failed to load project configuration")?;
                                         // => If load_config errors, wraps with this message
                                         // => Chain: "failed to load project configuration"
                                         // =>   caused by: "could not read config.toml"
                                         // =>   caused by: "No such file or directory"
 
    println!("Loaded config: {}", config);
    validate_structure(project_dir)
        .with_context(|| format!("validation failed for {}", project_dir.display()))?;
 
    Ok(())
}
 
fn load_config(dir: &Path) -> Result<String> {
    let config_path = dir.join("config.toml");
    let content = fs::read_to_string(&config_path)
        .with_context(|| format!("could not read {}", config_path.display()))?;
                                         // => Wraps the io::Error with the path
 
    Ok(content)
}
 
fn validate_structure(dir: &Path) -> Result<()> {
    let src = dir.join("src");
    if !src.is_dir() {
        anyhow::bail!("missing src/ directory in {}", dir.display());
                                         // => Creates error with formatted message
    }
    Ok(())
}
 
fn main() {
    // Simulate running validation on a project directory
    let project = Path::new(".");
 
    match run_validation(project) {
        Ok(())  => println!("Validation passed"),
        Err(e)  => {
            // Print the full error chain
            eprintln!("Error: {}", e);
                                         // => Outermost error only
 
            eprintln!("\nFull chain:");
            for cause in e.chain() {     // => .chain() iterates all causes
                eprintln!("  caused by: {}", cause);
            }
            std::process::exit(1);
        }
    }
}

use serde::{Deserialize, Serialize};
 
// Derive Serialize and Deserialize to enable JSON encoding/decoding
#[derive(Debug, Serialize, Deserialize)]
struct ValidationReport {
    tool: String,
    version: String,
    #[serde(rename = "totalFiles")]      // => JSON key "totalFiles" maps to Rust field total_files
    total_files: u32,
    errors: Vec<ValidationError>,
}
 
#[derive(Debug, Serialize, Deserialize)]
struct ValidationError {
    path: String,
    rule: String,
    #[serde(skip_serializing_if = "Option::is_none")]
                                         // => Skip this field in JSON if it's None
    line: Option<u32>,
}
 
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Serialize Rust struct to JSON string
    let report = ValidationReport {
        tool: String::from("my-checker"),
        version: String::from("0.1.0"),
        total_files: 42,
        errors: vec![
            ValidationError {
                path: String::from("src/bad_name.rs"),
                rule: String::from("file-naming"),
                line: Some(1),
            },
            ValidationError {
                path: String::from("README.MD"),
                rule: String::from("extension-case"),
                line: None,              // => Will be omitted from JSON (skip_serializing_if)
            },
        ],
    };
 
    let json = serde_json::to_string_pretty(&report)?;
                                         // => Serialize to pretty-printed JSON string
                                         // => Returns Result<String, serde_json::Error>
    println!("{}", json);
    // Output:
    // {
    //   "tool": "my-checker",
    //   "version": "0.1.0",
    //   "totalFiles": 42,
    //   "errors": [
    //     { "path": "src/bad_name.rs", "rule": "file-naming", "line": 1 },
    //     { "path": "README.MD", "rule": "extension-case" }
    //   ]
    // }
 
    // Deserialize JSON string back to Rust struct
    let json_input = r#"{"tool":"checker","version":"1.0","totalFiles":5,"errors":[]}"#;
    let parsed: ValidationReport = serde_json::from_str(json_input)?;
                                         // => Deserialize JSON string to ValidationReport
    println!("Parsed tool: {}", parsed.tool);
                                         // => Output: Parsed tool: checker
    println!("Parsed files: {}", parsed.total_files);
                                         // => Output: Parsed files: 5
 
    Ok(())
}

use serde::{Deserialize, Serialize};
 
#[derive(Debug, Serialize, Deserialize)]
struct ToolConfig {
    name: String,
    version: String,
    rules: Vec<String>,
    max_errors: u32,
    #[serde(default)]                   // => If key absent in YAML, use Default::default()
    verbose: bool,                       // => Default for bool is false
}
 
fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Deserialize from YAML string
    let yaml_config = r#"
name: my-checker
version: "0.1.0"
rules:
  - file-naming
  - line-length
  - missing-test
max_errors: 50
"#;
 
    let config: ToolConfig = serde_yml::from_str(yaml_config)?;
                                         // => Parse YAML to ToolConfig
    println!("Name: {}", config.name);   // => Output: Name: my-checker
    println!("Rules: {:?}", config.rules);
                                         // => Output: Rules: ["file-naming", "line-length", "missing-test"]
    println!("Verbose: {}", config.verbose);
                                         // => Output: Verbose: false (default applied)
 
    // Serialize Rust struct to YAML string
    let output_config = ToolConfig {
        name: String::from("my-checker"),
        version: String::from("0.2.0"),
        rules: vec![String::from("file-naming"), String::from("kebab-case")],
        max_errors: 100,
        verbose: true,
    };
 
    let yaml = serde_yml::to_string(&output_config)?;
                                         // => Serialize to YAML string
    println!("---\n{}", yaml);
    // Output:
    // ---
    // name: my-checker
    // version: 0.2.0
    // rules:
    // - file-naming
    // - kebab-case
    // max_errors: 100
    // verbose: true
 
    Ok(())
}

use std::collections::{BTreeMap, HashMap};
 
fn main() {
    // HashMap: non-deterministic iteration order
    let mut hash_counts: HashMap<&str, u32> = HashMap::new();
    hash_counts.insert("file-naming", 3);
    hash_counts.insert("line-length", 7);
    hash_counts.insert("missing-test", 1);
    hash_counts.insert("unused-import", 2);
 
    println!("HashMap order (non-deterministic):");
    for (key, count) in &hash_counts {
        println!("  {}: {}", key, count); // => Order changes between runs
    }
 
    // BTreeMap: sorted alphabetically by key
    let mut btree_counts: BTreeMap<&str, u32> = BTreeMap::new();
    btree_counts.insert("file-naming", 3);
    btree_counts.insert("line-length", 7);
    btree_counts.insert("missing-test", 1);
    btree_counts.insert("unused-import", 2);
 
    println!("\nBTreeMap order (always sorted):");
    for (key, count) in &btree_counts {
        println!("  {}: {}", key, count);
        // Output (always same order):
        //   file-naming: 3
        //   line-length: 7
        //   missing-test: 1
        //   unused-import: 2
    }
 
    // BTreeMap methods work same as HashMap
    btree_counts.entry("file-naming").and_modify(|v| *v += 1);
    println!("\nAfter increment: {:?}", btree_counts.get("file-naming"));
                                         // => Output: Some(4)
 
    // Collect from HashMap into BTreeMap for sorted output
    let sorted: BTreeMap<_, _> = hash_counts.iter().collect();
                                         // => .collect() with BTreeMap type annotation
                                         // => Sorts the HashMap's entries
    println!("\nSorted HashMap:");
    for (k, v) in &sorted {
        println!("  {}: {}", k, v);      // => Always alphabetical
    }
}

#[derive(Debug)]
struct CheckResult {
    name: String,
    passed: bool,
    message: String,
}
 
impl CheckResult {
    // Private helper: all named constructors call this
    fn new(name: impl Into<String>, passed: bool, message: impl Into<String>) -> Self {
                                         // => impl Into<String>: accepts both &str and String
                                         // => Covered in detail in Example 49
        Self {                           // => Self is an alias for CheckResult inside impl
            name: name.into(),           // => .into() converts &str or String to String
            passed,
            message: message.into(),
        }
    }
 
    // Named constructor: passing check
    pub fn passed(name: impl Into<String>) -> Self {
        Self::new(name, true, "")        // => Passing checks have no message
    }
 
    // Named constructor: failing check
    pub fn failed(name: impl Into<String>, message: impl Into<String>) -> Self {
        Self::new(name, false, message)
    }
 
    // Named constructor: warning (using passed=true to not block, but has message)
    pub fn warning(name: impl Into<String>, message: impl Into<String>) -> Self {
        Self::new(name, true, message)   // => Warning: doesn't block, but has message
    }
}
 
fn main() {
    // Named constructors are readable at the call site
    let r1 = CheckResult::passed("file-naming");
                                         // => Clear: this is a passing result
    let r2 = CheckResult::failed("line-length", "line 42 is 120 chars (max 80)");
                                         // => Clear: this is a failing result with reason
    let r3 = CheckResult::warning("file-size", "file is large (2MB), consider splitting");
 
    let results = vec![r1, r2, r3];
 
    for r in &results {
        if r.passed {
            println!("[PASS] {}", r.name);
        } else {
            println!("[FAIL] {}: {}", r.name, r.message);
        }
    }
    // Output:
    // [PASS] file-naming
    // [FAIL] line-length: line 42 is 120 chars (max 80)
    // [PASS] file-size
    // (warning is passed=true but has message — handle separately in reporting)
}

#[derive(Debug)]
struct CheckResult {
    name: String,
    passed: bool,
    message: String,
}
 
impl CheckResult {
    fn passed(name: &str) -> Self {
        Self { name: name.to_string(), passed: true, message: String::new() }
    }
    fn failed(name: &str, msg: &str) -> Self {
        Self { name: name.to_string(), passed: false, message: msg.to_string() }
    }
}
 
struct CheckSummary {
    total: u32,
    passed: u32,
    failed: u32,
}
 
impl CheckSummary {
    fn from_results(results: &[CheckResult]) -> Self {
                                         // => Takes a slice: works with Vec and arrays
        let total = results.len() as u32;// => Total count
        let passed = results.iter().filter(|r| r.passed).count() as u32;
                                         // => Count passing results
        Self {
            total,
            passed,
            failed: total - passed,      // => Derived: no need to count separately
        }
    }
 
    fn all_passed(&self) -> bool {       // => Convenience method
        self.failed == 0
    }
 
    fn exit_code(&self) -> i32 {         // => Conventional CLI exit codes
        if self.all_passed() { 0 } else { 1 }
    }
}
 
fn main() {
    // Collect results from multiple validators
    let mut results: Vec<CheckResult> = Vec::new();
 
    // Each validator adds its results
    results.push(CheckResult::passed("file-naming"));
    results.push(CheckResult::failed("line-length", "line 42 too long"));
    results.push(CheckResult::passed("test-coverage"));
    results.push(CheckResult::failed("missing-docs", "pub fn lacks doc comment"));
    results.push(CheckResult::passed("format-check"));
 
    // Print all results
    for r in &results {
        if r.passed {
            println!("[PASS] {}", r.name);
        } else {
            println!("[FAIL] {}: {}", r.name, r.message);
        }
    }
 
    // Compute summary
    let summary = CheckSummary::from_results(&results);
 
    println!("\n--- Summary ---");
    println!("Total:  {}", summary.total);   // => Output: Total: 5
    println!("Passed: {}", summary.passed);  // => Output: Passed: 3
    println!("Failed: {}", summary.failed);  // => Output: Failed: 2
 
    let code = summary.exit_code();
    println!("Exit: {}", code);              // => Output: Exit: 1 (failures present)
    std::process::exit(code);
}

struct Violation {
    path: String,
    rule: String,
    message: String,
}
 
impl Violation {
    // Without impl Into<String>: callers must pass String
    // fn new_verbose(path: String, rule: String, message: String) -> Self { ... }
    // Caller: Violation::new_verbose(String::from("src/main.rs"), String::from("rule"), ...)
 
    // With impl Into<String>: callers pass &str or String
    fn new(
        path: impl Into<String>,         // => Accepts &str or String
        rule: impl Into<String>,
        message: impl Into<String>,
    ) -> Self {
        Self {
            path: path.into(),           // => .into() converts to String
            rule: rule.into(),
            message: message.into(),
        }
    }
}
 
fn main() {
    // With impl Into<String>: no .to_string() or String::from() needed at call sites
    let v1 = Violation::new(
        "src/main.rs",                   // => &str literal, auto-converted to String
        "file-naming",
        "filename should be kebab-case",
    );
 
    // Also accepts owned Strings
    let path = String::from("src/lib.rs");
    let v2 = Violation::new(
        path,                            // => Owned String, moved in (no clone needed)
        "missing-docs",
        "public function lacks documentation",
    );
 
    println!("{}: {}", v1.path, v1.message);
                                         // => Output: src/main.rs: filename should be kebab-case
    println!("{}: {}", v2.path, v2.message);
                                         // => Output: src/lib.rs: public function lacks documentation
 
    // Without impl Into<String>, callers would write:
    // Violation::new(String::from("src/main.rs"), String::from("rule"), String::from("msg"))
    // That's 3 unnecessary String::from() calls per violation
}

use std::io::{self, Write};
 
struct CheckResult {
    name: String,
    passed: bool,
    message: String,
}
 
// Takes &mut dyn Write: testable with Vec<u8>, usable with stdout in production
fn write_report(
    out: &mut dyn Write,                 // => Any type implementing Write
    results: &[CheckResult],
) -> io::Result<()> {
    for r in results {
        if r.passed {
            writeln!(out, "[PASS] {}", r.name)?;
                                         // => writeln! to the dyn Write target
                                         // => ? propagates io::Error
        } else {
            writeln!(out, "[FAIL] {}: {}", r.name, r.message)?;
        }
    }
 
    let (pass, fail): (Vec<_>, Vec<_>) = results.iter().partition(|r| r.passed);
    writeln!(out, "---")?;
    writeln!(out, "Passed: {} / {}", pass.len(), results.len())?;
    Ok(())
}
 
fn main() {
    let results = vec![
        CheckResult { name: "naming".into(), passed: true, message: String::new() },
        CheckResult { name: "length".into(), passed: false, message: "too long".into() },
    ];
 
    // Production: write to stdout
    write_report(&mut io::stdout(), &results).unwrap();
}
 
#[cfg(test)]
mod tests {
    use super::*;
 
    #[test]
    fn test_report_output() {
        let results = vec![
            CheckResult { name: "naming".into(), passed: true, message: String::new() },
            CheckResult { name: "length".into(), passed: false, message: "too long".into() },
        ];
 
        let mut buffer: Vec<u8> = Vec::new();
        write_report(&mut buffer, &results).unwrap();
                                         // => Writes to Vec<u8> in-memory buffer
                                         // => No stdout capture needed
 
        let output = String::from_utf8(buffer).unwrap();
        assert!(output.contains("[PASS] naming"));
        assert!(output.contains("[FAIL] length: too long"));
        assert!(output.contains("Passed: 1 / 2"));
    }
}

use std::env;
 
fn main() {
    // Read a specific environment variable
    match env::var("HOME") {
        Ok(home) => println!("HOME={}", home),
                                         // => Output: HOME=/home/username (on Unix)
        Err(e)   => println!("HOME not set: {}", e),
    }
 
    // Convert Result to Option for simpler handling
    let editor = env::var("EDITOR").ok();// => .ok(): Ok(s) -> Some(s), Err -> None
    let editor = editor.as_deref().unwrap_or("vi");
                                         // => .as_deref(): Option<String> -> Option<&str>
                                         // => .unwrap_or("vi"): use "vi" if not set
    println!("Editor: {}", editor);
 
    // Read with a default value
    let max_workers: u32 = env::var("MY_TOOL_WORKERS")
        .ok()
        .and_then(|s| s.parse().ok())    // => Parse string to u32, None if parse fails
        .unwrap_or(4);                   // => Default to 4 workers
    println!("Workers: {}", max_workers);
 
    // Check for common CI environment variables
    let in_ci = env::var("CI").is_ok()
        || env::var("GITHUB_ACTIONS").is_ok()
        || env::var("TRAVIS").is_ok();
    println!("In CI: {}", in_ci);
 
    // Iterate all environment variables
    let path_vars: Vec<_> = env::vars()
        .filter(|(key, _)| key.starts_with("PATH"))
                                         // => Filter env vars whose key starts with PATH
        .collect();
    println!("PATH-related vars: {:?}", path_vars);
 
    // Current directory
    let cwd = env::current_dir().expect("could not get current directory");
    println!("CWD: {}", cwd.display());
}

use std::process::ExitCode;
 
fn main() -> ExitCode {                  // => Return ExitCode from main for clean exit
    let args: Vec<String> = std::env::args().collect();
 
    if args.len() < 2 {
        eprintln!("Usage: {} <path>", args[0]);
        return ExitCode::from(2);        // => Exit code 2: usage error
                                         // => Convention: 2 = bad usage / missing arguments
    }
 
    let path = &args[1];
    let result = run_check(path);
 
    match result {
        Ok(violations) if violations == 0 => {
            println!("All checks passed");
            ExitCode::SUCCESS            // => ExitCode::SUCCESS = 0
        }
        Ok(violations) => {
            println!("{} violations found", violations);
            ExitCode::FAILURE            // => ExitCode::FAILURE = 1
        }
        Err(e) => {
            eprintln!("Error: {}", e);
            ExitCode::FAILURE            // => Exit code 1: runtime error
        }
    }
}
 
fn run_check(_path: &str) -> Result<u32, String> {
    // Simulate checking: returns number of violations
    Ok(3)                                // => 3 violations found
}
 
// Alternative: std::process::exit() for imperative control
fn _imperative_exit_example() {
    let critical_failure = true;
    if critical_failure {
        eprintln!("Critical failure — cannot continue");
        std::process::exit(1);           // => Terminates immediately, does not unwind
                                         // => Destructors NOT called (unlike normal return)
    }
}

use clap::{Parser, ValueEnum};
 
#[derive(Debug, Clone, ValueEnum)]       // => ValueEnum: clap parses string to variant
enum OutputFormat {
    Text,
    Json,
    Markdown,
}
 
#[derive(Parser)]
struct Cli {
    #[arg(long, value_enum, default_value = "text")]
    format: OutputFormat,                // => --format text/json/markdown
}
 
impl std::fmt::Display for OutputFormat {// => Enable println!("{}", format)
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            OutputFormat::Text     => write!(f, "text"),
            OutputFormat::Json     => write!(f, "json"),
            OutputFormat::Markdown => write!(f, "markdown"),
        }
    }
}
 
fn print_results(format: &OutputFormat, violations: &[(&str, &str)]) {
    match format {
        OutputFormat::Text => {          // => Plain text output
            for (file, rule) in violations {
                println!("{}: {}", file, rule);
            }
        }
        OutputFormat::Json => {          // => JSON output
            println!("[");
            for (i, (file, rule)) in violations.iter().enumerate() {
                let comma = if i + 1 < violations.len() { "," } else { "" };
                println!("  {{\"file\":\"{}\",\"rule\":\"{}\"}}{}", file, rule, comma);
            }
            println!("]");
        }
        OutputFormat::Markdown => {      // => Markdown table output
            println!("| File | Rule |");
            println!("|------|------|");
            for (file, rule) in violations {
                println!("| {} | {} |", file, rule);
            }
        }
    }
}
 
fn main() {
    let cli = Cli::parse();
    println!("Output format: {}", cli.format);
 
    let violations = vec![
        ("src/BadName.rs", "file-naming"),
        ("src/lib.rs", "missing-test"),
    ];
 
    print_results(&cli.format, &violations);
}

fn main() {
    let dirs = vec!["src", "tests", "examples"];
    let extensions = vec!["rs", "toml"];
 
    // .flat_map(): for each element, produce multiple outputs, then flatten
    let file_patterns: Vec<String> = dirs.iter()
        .flat_map(|dir| {                // => Each dir produces multiple patterns
            extensions.iter().map(move |ext| format!("{}/*.{}", dir, ext))
                             // => move: capture dir by value in inner closure
        })
        .collect();
    println!("{:?}", file_patterns);
    // Output: ["src/*.rs", "src/*.toml", "tests/*.rs", "tests/*.toml", "examples/*.rs", "examples/*.toml"]
 
    // .chain(): concatenate two iterators
    let a = vec![1u32, 2, 3];
    let b = vec![4u32, 5, 6];
    let combined: Vec<u32> = a.iter().chain(b.iter()).copied().collect();
    println!("{:?}", combined);          // => [1, 2, 3, 4, 5, 6]
 
    // .enumerate(): (index, element) pairs
    let files = vec!["main.rs", "lib.rs", "utils.rs"];
    for (i, file) in files.iter().enumerate() {
        println!("{}: {}", i + 1, file); // => 1: main.rs, 2: lib.rs, 3: utils.rs
    }
 
    // .zip(): parallel iteration
    let names = vec!["naming", "length", "coverage"];
    let counts = vec![3u32, 1, 0];
    let pairs: Vec<_> = names.iter().zip(counts.iter()).collect();
    for (name, count) in &pairs {
        println!("{}: {} violations", name, count);
    }
 
    // .take() and .skip()
    let numbers: Vec<u32> = (1..=10).collect();
    let middle: Vec<u32> = numbers.iter().skip(2).take(5).copied().collect();
                                         // => Skip first 2, take next 5
    println!("{:?}", middle);            // => [3, 4, 5, 6, 7]
 
    // Combining multiple adapters
    let report: Vec<String> = files.iter()
        .enumerate()
        .filter(|(_, f)| f.ends_with(".rs"))
        .map(|(i, f)| format!("  {:>2}. {}", i + 1, f))
        .collect();
 
    for line in &report {
        println!("{}", line);
    }
}

fn main() {
    let mut errors = vec![
        "line-length",
        "file-naming",
        "missing-test",
        "line-length",  // => Duplicate
        "unused-import",
        "file-naming",  // => Duplicate
    ];
 
    // .sort(): sort in-place (lexicographic for &str)
    errors.sort();                       // => Mutates errors in-place
    println!("{:?}", errors);
    // Output: ["file-naming", "file-naming", "line-length", "line-length", "missing-test", "unused-import"]
 
    // .dedup(): remove consecutive duplicates (requires sorted input for full dedup)
    errors.dedup();                      // => Removes consecutive duplicates
    println!("{:?}", errors);
    // Output: ["file-naming", "line-length", "missing-test", "unused-import"]
 
    // .sort_by(): custom sort order
    let mut counts: Vec<(&str, u32)> = vec![
        ("naming", 3), ("length", 10), ("coverage", 1)
    ];
    counts.sort_by(|a, b| b.1.cmp(&a.1)); // => Sort by count descending
                                            // => b.1.cmp(&a.1): reverse order
    println!("{:?}", counts);
    // Output: [("length", 10), ("naming", 3), ("coverage", 1)]
 
    // .retain(): keep only matching elements (mutates in-place)
    let mut rules = vec!["naming", "length", "coverage", "format", "docs"];
    rules.retain(|rule| rule.len() > 5); // => Keep rules with name longer than 5 chars
    println!("{:?}", rules);             // => ["length", "coverage", "format"]
 
    // .extend(): append all elements from an iterator
    let mut all_errors: Vec<String> = vec![String::from("error-a")];
    let more = vec![String::from("error-b"), String::from("error-c")];
    all_errors.extend(more.into_iter()); // => Moves all elements from more into all_errors
    println!("{:?}", all_errors);        // => ["error-a", "error-b", "error-c"]
 
    // .drain(): remove and iterate a range of elements
    let mut queue: Vec<u32> = vec![1, 2, 3, 4, 5];
    let first_three: Vec<u32> = queue.drain(..3).collect();
                                         // => Removes elements 0..3, returns them
    println!("Drained: {:?}", first_three);// => [1, 2, 3]
    println!("Remaining: {:?}", queue);    // => [4, 5]
}

// This code lives in tests/integration_test.rs or in #[cfg(test)] module
// The binary must be built first (cargo test builds it automatically)
 
// Cargo.toml additions:
// [dev-dependencies]
// assert_cmd = "2.0"
// predicates = "3.1"
 
#[cfg(test)]
mod tests {
    use assert_cmd::Command;             // => Command: wraps a CLI binary
 
    #[test]
    fn test_no_args_shows_help() {
        let mut cmd = Command::cargo_bin("my-checker").unwrap();
                                         // => Find the binary built by cargo
                                         // => Automatically rebuilds if source changed
        cmd.assert()
           .failure()                    // => Exit code != 0 (help exits with 1 or 2)
           .stderr(predicates::str::contains("Usage"));
                                         // => stderr contains "Usage" string
    }
 
    #[test]
    fn test_check_current_dir() {
        let mut cmd = Command::cargo_bin("my-checker").unwrap();
        cmd.arg("check")                 // => Pass "check" as first argument
           .arg("--path").arg(".")       // => --path with value "."
           .assert()
           .success();                   // => Exit code 0
    }
 
    #[test]
    fn test_version_flag() {
        let mut cmd = Command::cargo_bin("my-checker").unwrap();
        cmd.arg("--version")
           .assert()
           .success()
           .stdout(predicates::str::contains("0.1.0"));
                                         // => stdout contains version string
    }
 
    #[test]
    fn test_invalid_subcommand() {
        let mut cmd = Command::cargo_bin("my-checker").unwrap();
        cmd.arg("nonexistent-command")
           .assert()
           .failure();                   // => Exit code != 0 for unknown subcommand
    }
}