Rust 编码规范¶

// 差
let data = parse(s);
let result = execute(data);

// 好
let pipeline = parse(input_line);
let exit_status = execute(pipeline);

// 好：最小化公开面
pub(crate) struct Pipeline {
    commands: Vec<Command>,      // 私有字段
}

impl Pipeline {
    pub(crate) fn new(commands: Vec<Command>) -> Self { ... }
    pub(crate) fn execute(&self) -> Result<Vec<i32>> { ... }
}

use std::collections::HashMap;
use std::path::PathBuf;

use nix::sys::signal::Signal;
use nix::unistd::Pid;

use crate::ast::{Command, Pipeline};
use crate::error::ShellError;

// 差
fn execute(cmd: &Command, background: bool) -> Result<i32> { ... }

// 好
enum ExecutionMode {
    Foreground,
    Background,
}

fn execute(cmd: &Command, mode: ExecutionMode) -> Result<i32> { ... }

// 差：两个 i32 容易传错顺序
fn wait_pid(pid: i32, timeout_ms: i32) -> Result<ExitStatus> { ... }

// 好：编译器帮你检查
#[derive(Debug, Clone, Copy)]
struct ProcessId(i32);

#[derive(Debug, Clone, Copy)]
struct TimeoutMs(u64);

fn wait_pid(pid: ProcessId, timeout: TimeoutMs) -> Result<ExitStatus> { ... }

impl Shell {
    /// 构造一个新的 Shell 实例。
    ///
    /// 此方法不分配终端、不设置信号处理——只是创建数据结构。
    pub(crate) fn new() -> Self {
        Self {
            jobs: JobTable::new(),
            exit_code: 0,
        }
    }
}

use thiserror::Error;

#[derive(Error, Debug)]
pub(crate) enum ShellError {
    #[error("command not found: {0}")]
    CommandNotFound(String),

    #[error("failed to redirect fd {fd} to {target}")]
    Redirection { fd: i32, target: String, #[source] source: io::Error },

    #[error("pipe creation failed")]
    Pipe(#[source] io::Error),

    #[error("fork failed")]
    Fork(#[source] nix::Error),

    #[error("signal error: {0}")]
    Signal(String),
}

use anyhow::Context;

fn run_script(path: &Path) -> anyhow::Result<()> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("failed to read script: {}", path.display()))?;
    // ...
}

// 差：消息只是描述了失败场景
let home = std::env::var("HOME").expect("HOME not set");

// 好：解释了为什么不可能失败
let home = std::env::var("HOME")
    .expect("POSIX requires HOME to be set for login shells");

// 更好：用 Result 传播
let home = std::env::var("HOME").context("HOME environment variable not set")?;

// 差：errno 可能被中间调用覆盖
let ret = unsafe { libc::close(fd) };
if ret < 0 {
    let msg = format!("close({fd}) failed"); // errno 可能已经不是原来的了
}

// 好：使用 nix 封装
nix::unistd::close(fd).context("close stdin in child process")?;

// 如果必须用 libc：立即保存 errno
let ret = unsafe { libc::close(fd) };
if ret < 0 {
    let err = io::Error::last_os_error();
    return Err(ShellError::Syscall { call: "close", fd, source: err });
}

// 差：只看一眼代码不知道为什么要 clone
let cmd = commands[0].clone();
execute(cmd);

// 好：借用即可
execute(&commands[0]);

// 可接受：有明确语义需求
let cmd = commands[0].clone(); // Clone：需要把 cmd 移到后台线程
thread::spawn(move || execute(cmd));

// 差：函数不需要所有权
fn parse_command(line: String) -> Command { ... }

// 好
fn parse_command(line: &str) -> Command { ... }

/// Parses an input line into an AST of shell commands.
///
/// This function tokenizes the input and constructs a [`Pipeline`] of
/// [`Command`] nodes representing pipes, redirections, and boolean
/// operators. It does **not** interpret quoted strings or perform
/// variable expansion—only syntax-level parsing.
///
/// # Errors
///
/// Returns [`ShellError::Parse`] if the input contains unmatched
/// quotes or malformed redirections.
///
/// # Examples
///
/// ```
/// use osh::parser::parse;
///
/// let pipeline = parse("ls -la | wc -l")?;
/// assert_eq!(pipeline.len(), 2);
/// # Ok::<(), osh::error::ShellError>(())
/// ```
pub(crate) fn parse(input: &str) -> Result<Pipeline, ShellError> {
    // ...
}

//! Shell command executor.
//!
//! This module handles the execution of a parsed [`Pipeline`]:
//! - Forks child processes for external commands.
//! - Routes built-in commands to the [`builtins`](super::builtins) module.
//! - Manages pipe connections between pipeline stages.
//!
//! # Safety
//!
//! This module uses `fork(2)` and `execve(2)`. See [`fork`] for the
//! restrictions on signal-unsafe operations between fork and exec.

/// Returns the exit status of this [`Job`].
///
/// If the job is still running, returns [`None`].
///
/// [`Job`]: crate::jobs::Job
pub(crate) fn status(&self) -> Option<i32> { ... }

/// ``` 代码块会自动被 `cargo test` 编译和运行。利用这一点确保文档中的示例永远正确。
///
/// ```
/// use osh::Shell;
///
/// let mut shell = Shell::new();
/// let exit_code = shell.run_command("echo hello")?;
/// assert_eq!(exit_code, 0);
/// # Ok::<(), osh::error::ShellError>(())
/// ```

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

    #[test]
    fn test_parse__empty_input_returns_empty_pipeline() {
        let result = parse("").unwrap();
        assert!(result.commands.is_empty());
    }

    #[test]
    fn test_parse__single_command_no_args() {
        let pipeline = parse("ls").unwrap();
        assert_eq!(pipeline.commands.len(), 1);
        assert_eq!(pipeline.commands[0].name, "ls");
        assert!(pipeline.commands[0].args.is_empty());
    }

    #[test]
    fn test_parse__unmatched_quote_returns_error() {
        let result = parse("echo \"hello");
        assert!(matches!(result, Err(ShellError::Parse(_))));
    }
}

// tests/shell_integration.rs
use std::process::Command;

#[test]
fn test_shell_executes_simple_command() {
    let output = Command::new("cargo")
        .args(["run", "--", "-c", "echo hello"])
        .output()
        .unwrap();
    assert!(output.status.success());
    assert_eq!(String::from_utf8_lossy(&output.stdout).trim(), "hello");
}

#[test]
fn test_word_split() {
    let cases = vec![
        ("", vec![]),
        ("ls", vec!["ls"]),
        ("ls -la", vec!["ls", "-la"]),
        ("echo \"a b\"", vec!["echo", "a b"]),
    ];
    for (input, expected) in cases {
        assert_eq!(split_words(input), expected,
            "failed on input: {input:?}");
    }
}

// SAFETY: 此处调用 libc::tcgetpgrp 获取当前终端的前台进程组。
// 前提条件：
// 1. fd 是一个已打开的终端文件描述符，由父进程在 fork 前打开。
// 2. 此函数的调用发生在子进程执行 execve 之前，此时仍为单线程。
// 3. 返回值立即检查，不会传播无效的 pid_t。
let pgid = unsafe { libc::tcgetpgrp(fd) };

/// 安全封装：获取终端前台进程组 ID。
///
/// # Errors
///
/// 如果 fd 不是有效的终端文件描述符，返回 `ShellError::Syscall`。
pub(crate) fn tcgetpgrp(fd: i32) -> Result<libc::pid_t, ShellError> {
    // SAFETY: fd 由调用者提供，调用者保证它是已打开的终端 fd。
    // 不涉及多线程竞争——shell 在主线程中调用此函数。
    let pgid = unsafe { libc::tcgetpgrp(fd) };
    if pgid == -1 {
        return Err(ShellError::Syscall {
            call: "tcgetpgrp",
            source: io::Error::last_os_error(),
        });
    }
    Ok(pgid)
}

#![warn(clippy::pedantic)]
#![warn(clippy::unwrap_used)]        // 标记所有 unwrap() 供审查
#![warn(clippy::expect_used)]        // 标记所有 expect() 供审查
#![warn(clippy::todo)]               // 禁止提交 TODO 到 main 分支