rumdl_lib/rules/

md014_commands_show_output.rs

//!
//! Rule MD014: Commands should show output
//!
//! See [docs/md014.md](../../docs/md014.md) for full documentation, configuration, and examples.

use crate::rule::{Fix, LintError, LintResult, LintWarning, Rule, RuleCategory, Severity};
use crate::utils::range_utils::calculate_match_range;
use regex::Regex;
use std::sync::LazyLock;
use toml;

mod md014_config;
use md014_config::MD014Config;

// Command detection patterns
static COMMAND_PATTERN: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^\s*[$>]\s+\S+").unwrap());
static SHELL_LANG_PATTERN: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"^(?i)(bash|sh|shell|console|terminal)").unwrap());
static DOLLAR_PROMPT_PATTERN: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"^\s*([$>])").unwrap());

#[derive(Clone, Default)]
pub struct MD014CommandsShowOutput {
    config: MD014Config,
}

impl MD014CommandsShowOutput {
    pub(crate) fn default_block_would_edit(opener: &str, lines: &[&str]) -> bool {
        !Self::default()
            .command_lines_without_output(lines, Self::get_code_block_language(opener))
            .is_empty()
    }

    pub fn new() -> Self {
        Self::default()
    }

    pub fn with_show_output(show_output: bool) -> Self {
        Self {
            config: MD014Config { show_output },
        }
    }

    pub fn from_config_struct(config: MD014Config) -> Self {
        Self { config }
    }

    fn is_command_line(&self, line: &str) -> bool {
        COMMAND_PATTERN.is_match(line)
    }

    fn is_shell_language(&self, lang: &str) -> bool {
        SHELL_LANG_PATTERN.is_match(lang)
    }

    fn is_output_line(&self, line: &str) -> bool {
        let trimmed = line.trim();
        !trimmed.is_empty() && !trimmed.starts_with('$') && !trimmed.starts_with('>') && !trimmed.starts_with('#')
    }

    fn is_no_output_command(&self, cmd: &str) -> bool {
        let cmd = cmd.trim().to_lowercase();

        // Only skip commands that produce NO output by design.
        // Commands that produce output (even if verbose) should NOT be skipped -
        // the rule's intent is to encourage showing output when using $ prompts.

        // Shell built-ins and commands that produce no terminal output
        cmd.starts_with("cd ")
            || cmd == "cd"
            || cmd.starts_with("mkdir ")
            || cmd.starts_with("touch ")
            || cmd.starts_with("rm ")
            || cmd.starts_with("mv ")
            || cmd.starts_with("cp ")
            || cmd.starts_with("export ")
            || cmd.starts_with("set ")
            || cmd.starts_with("alias ")
            || cmd.starts_with("unset ")
            || cmd.starts_with("source ")
            || cmd.starts_with(". ")
            || cmd == "true"
            || cmd == "false"
            || cmd.starts_with("sleep ")
            || cmd.starts_with("wait ")
            || cmd.starts_with("pushd ")
            || cmd.starts_with("popd")

            // Shell redirects (output goes to file, not terminal)
            || cmd.contains(" > ")
            || cmd.contains(" >> ")

            // Git commands that produce no output on success
            || cmd.starts_with("git add ")
            || cmd.starts_with("git checkout ")
            || cmd.starts_with("git stash")
            || cmd.starts_with("git reset ")
    }

    fn fix_command_block(&self, block: &[&str]) -> String {
        block
            .iter()
            .map(|line| {
                let trimmed = line.trim_start();
                if self.is_command_line(line) {
                    let spaces = line.len() - trimmed.len();
                    let cmd = trimmed[1..].trim_start();
                    format!("{}{}", " ".repeat(spaces), cmd)
                } else {
                    line.to_string()
                }
            })
            .collect::<Vec<_>>()
            .join("\n")
    }

    fn get_code_block_language(block_start: &str) -> &str {
        block_start
            .trim_start()
            .trim_start_matches("```")
            .split_whitespace()
            .next()
            .unwrap_or("")
    }

    /// Find all command lines in the block that should produce output.
    /// Skips no-output commands (cd, mkdir, etc.).
    fn command_lines_without_output<'a>(&self, block: &[&'a str], lang: &str) -> Vec<(usize, &'a str)> {
        if !self.config.show_output
            || !self.is_shell_language(lang)
            || block.iter().any(|line| self.is_output_line(line))
        {
            return Vec::new();
        }

        let mut results = Vec::new();
        for (i, line) in block.iter().enumerate() {
            if self.is_command_line(line) {
                let cmd = line.trim()[1..].trim();
                if !self.is_no_output_command(cmd) {
                    results.push((i, *line));
                }
            }
        }
        results
    }
}

impl Rule for MD014CommandsShowOutput {
    fn native_format_policy(&self) -> Option<crate::format_proof::NativeFormatPolicy> {
        (self.config == Default::default()).then_some(crate::format_proof::NativeFormatPolicy::for_rule::<Self>(14))
    }

    fn name(&self) -> &'static str {
        "MD014"
    }

    fn description(&self) -> &'static str {
        "Commands in code blocks should show output"
    }

    fn category(&self) -> RuleCategory {
        RuleCategory::CodeBlock
    }

    fn check(&self, ctx: &crate::lint_context::LintContext) -> LintResult {
        let content = ctx.content;

        let mut warnings = Vec::new();

        let mut current_block = Vec::new();

        let mut in_code_block = false;

        let mut block_start_line = 0;

        let mut current_lang = "";

        for (line_num, line) in content.lines().enumerate() {
            if line.trim_start().starts_with("```") {
                if in_code_block {
                    // End of code block
                    let command_lines = self.command_lines_without_output(&current_block, current_lang);
                    if !command_lines.is_empty() {
                        let fix = Fix::new(
                            {
                                // Replace the content line(s) between the fences
                                let content_start_line = block_start_line + 1; // Line after opening fence (0-indexed)
                                let content_end_line = line_num - 1; // Line before closing fence (0-indexed)

                                // Calculate byte range for the content lines including their newlines
                                let start_byte = ctx.line_start_byte(content_start_line + 1).unwrap_or(0); // +1 for 1-indexed
                                let end_byte = ctx.line_start_byte(content_end_line + 2).unwrap_or(start_byte); // +2 to include newline after last content line
                                start_byte..end_byte
                            },
                            format!("{}\n", self.fix_command_block(&current_block)),
                        );

                        for (cmd_line_idx, cmd_line) in &command_lines {
                            let cmd_line_num = block_start_line + 1 + cmd_line_idx + 1; // +1 for fence, +1 for 1-indexed

                            // Find and highlight the dollar sign or prompt
                            if let Some(cap) = DOLLAR_PROMPT_PATTERN.captures(cmd_line) {
                                let match_obj = cap.get(1).unwrap(); // The $ or > character
                                let (start_line, start_col, end_line, end_col) =
                                    calculate_match_range(cmd_line_num, cmd_line, match_obj.start(), match_obj.len());

                                // Extract command text from this specific line
                                let cmd_text = cmd_line.trim()[1..].trim();
                                let message = if cmd_text.is_empty() {
                                    "Command should show output (add example output or remove $ prompt)".to_string()
                                } else {
                                    format!(
                                        "Command '{cmd_text}' should show output (add example output or remove $ prompt)"
                                    )
                                };

                                warnings.push(LintWarning {
                                    rule_name: Some(self.name().to_string()),
                                    line: start_line,
                                    column: start_col,
                                    end_line,
                                    end_column: end_col,
                                    message,
                                    severity: Severity::Warning,
                                    fix: Some(fix.clone()),
                                });
                            }
                        }
                    }
                    current_block.clear();
                } else {
                    // Start of code block
                    block_start_line = line_num;
                    current_lang = Self::get_code_block_language(line);
                }
                in_code_block = !in_code_block;
            } else if in_code_block {
                current_block.push(line);
            }
        }

        Ok(warnings)
    }

    fn fixes_from_diagnostics(&self) -> bool {
        true
    }

    fn fix(&self, ctx: &crate::lint_context::LintContext) -> Result<String, LintError> {
        if self.should_skip(ctx) {
            return Ok(ctx.content.to_string());
        }
        let warnings = self.check(ctx)?;
        if warnings.is_empty() {
            return Ok(ctx.content.to_string());
        }
        let warnings =
            crate::utils::fix_utils::filter_warnings_by_inline_config(warnings, ctx.inline_config(), self.name());
        crate::utils::fix_utils::apply_warning_fixes(ctx.content, &warnings)
            .map_err(crate::rule::LintError::InvalidInput)
    }

    fn as_any(&self) -> &dyn std::any::Any {
        self
    }

    fn should_skip(&self, ctx: &crate::lint_context::LintContext) -> bool {
        // Skip if content is empty or has no code blocks
        ctx.content.is_empty() || !ctx.likely_has_code()
    }

    crate::impl_rule_config_methods!(MD014Config);
}

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

    #[test]
    fn test_is_command_line() {
        let rule = MD014CommandsShowOutput::new();
        assert!(rule.is_command_line("$ echo test"));
        assert!(rule.is_command_line("  $ ls -la"));
        assert!(rule.is_command_line("> pwd"));
        assert!(rule.is_command_line("   > cd /home"));
        assert!(!rule.is_command_line("echo test"));
        assert!(!rule.is_command_line("# comment"));
        assert!(!rule.is_command_line("output line"));
    }

    #[test]
    fn test_is_shell_language() {
        let rule = MD014CommandsShowOutput::new();
        assert!(rule.is_shell_language("bash"));
        assert!(rule.is_shell_language("BASH"));
        assert!(rule.is_shell_language("sh"));
        assert!(rule.is_shell_language("shell"));
        assert!(rule.is_shell_language("Shell"));
        assert!(rule.is_shell_language("console"));
        assert!(rule.is_shell_language("CONSOLE"));
        assert!(rule.is_shell_language("terminal"));
        assert!(rule.is_shell_language("Terminal"));
        assert!(!rule.is_shell_language("python"));
        assert!(!rule.is_shell_language("javascript"));
        assert!(!rule.is_shell_language(""));
    }

    #[test]
    fn test_is_output_line() {
        let rule = MD014CommandsShowOutput::new();
        assert!(rule.is_output_line("output text"));
        assert!(rule.is_output_line("   some output"));
        assert!(rule.is_output_line("file1 file2"));
        assert!(!rule.is_output_line(""));
        assert!(!rule.is_output_line("   "));
        assert!(!rule.is_output_line("$ command"));
        assert!(!rule.is_output_line("> prompt"));
        assert!(!rule.is_output_line("# comment"));
    }

    #[test]
    fn test_is_no_output_command() {
        let rule = MD014CommandsShowOutput::new();

        // Shell built-ins that produce no output
        assert!(rule.is_no_output_command("cd /home"));
        assert!(rule.is_no_output_command("cd"));
        assert!(rule.is_no_output_command("mkdir test"));
        assert!(rule.is_no_output_command("touch file.txt"));
        assert!(rule.is_no_output_command("rm -rf dir"));
        assert!(rule.is_no_output_command("mv old new"));
        assert!(rule.is_no_output_command("cp src dst"));
        assert!(rule.is_no_output_command("export VAR=value"));
        assert!(rule.is_no_output_command("set -e"));
        assert!(rule.is_no_output_command("source ~/.bashrc"));
        assert!(rule.is_no_output_command(". ~/.profile"));
        assert!(rule.is_no_output_command("alias ll='ls -la'"));
        assert!(rule.is_no_output_command("unset VAR"));
        assert!(rule.is_no_output_command("true"));
        assert!(rule.is_no_output_command("false"));
        assert!(rule.is_no_output_command("sleep 5"));
        assert!(rule.is_no_output_command("pushd /tmp"));
        assert!(rule.is_no_output_command("popd"));

        // Case insensitive (lowercased internally)
        assert!(rule.is_no_output_command("CD /HOME"));
        assert!(rule.is_no_output_command("MKDIR TEST"));

        // Shell redirects (output goes to file)
        assert!(rule.is_no_output_command("echo 'test' > file.txt"));
        assert!(rule.is_no_output_command("cat input.txt > output.txt"));
        assert!(rule.is_no_output_command("echo 'append' >> log.txt"));

        // Git commands that produce no output on success
        assert!(rule.is_no_output_command("git add ."));
        assert!(rule.is_no_output_command("git checkout main"));
        assert!(rule.is_no_output_command("git stash"));
        assert!(rule.is_no_output_command("git reset HEAD~1"));

        // Commands that PRODUCE output (should NOT be skipped)
        assert!(!rule.is_no_output_command("ls -la"));
        assert!(!rule.is_no_output_command("echo test")); // echo without redirect
        assert!(!rule.is_no_output_command("pwd"));
        assert!(!rule.is_no_output_command("cat file.txt")); // cat without redirect
        assert!(!rule.is_no_output_command("grep pattern file"));

        // Installation commands PRODUCE output (should NOT be skipped)
        assert!(!rule.is_no_output_command("pip install requests"));
        assert!(!rule.is_no_output_command("npm install express"));
        assert!(!rule.is_no_output_command("cargo install ripgrep"));
        assert!(!rule.is_no_output_command("brew install git"));

        // Build commands PRODUCE output (should NOT be skipped)
        assert!(!rule.is_no_output_command("cargo build"));
        assert!(!rule.is_no_output_command("npm run build"));
        assert!(!rule.is_no_output_command("make"));

        // Docker commands PRODUCE output (should NOT be skipped)
        assert!(!rule.is_no_output_command("docker ps"));
        assert!(!rule.is_no_output_command("docker compose up"));
        assert!(!rule.is_no_output_command("docker run myimage"));

        // Git commands that PRODUCE output (should NOT be skipped)
        assert!(!rule.is_no_output_command("git status"));
        assert!(!rule.is_no_output_command("git log"));
        assert!(!rule.is_no_output_command("git diff"));
    }

    #[test]
    fn test_fix_command_block() {
        let rule = MD014CommandsShowOutput::new();
        let block = vec!["$ echo test", "$ ls -la"];
        assert_eq!(rule.fix_command_block(&block), "echo test\nls -la");

        let indented = vec!["    $ echo test", "  $ pwd"];
        assert_eq!(rule.fix_command_block(&indented), "    echo test\n  pwd");

        let mixed = vec!["> cd /home", "$ mkdir test"];
        assert_eq!(rule.fix_command_block(&mixed), "cd /home\nmkdir test");
    }

    #[test]
    fn test_get_code_block_language() {
        assert_eq!(MD014CommandsShowOutput::get_code_block_language("```bash"), "bash");
        assert_eq!(MD014CommandsShowOutput::get_code_block_language("```shell"), "shell");
        assert_eq!(
            MD014CommandsShowOutput::get_code_block_language("   ```console"),
            "console"
        );
        assert_eq!(
            MD014CommandsShowOutput::get_code_block_language("```bash {.line-numbers}"),
            "bash"
        );
        assert_eq!(MD014CommandsShowOutput::get_code_block_language("```"), "");
    }

    #[test]
    fn test_command_lines_without_output() {
        let rule = MD014CommandsShowOutput::with_show_output(true);

        let multiple = ["# comment", "$ echo one", "$ cd /tmp", "$ echo two"];
        assert_eq!(
            rule.command_lines_without_output(&multiple, "bash"),
            vec![(1, "$ echo one"), (3, "$ echo two")]
        );

        // Commands without output should be flagged
        let block1 = vec!["$ echo test"];
        assert_eq!(
            rule.command_lines_without_output(&block1, "bash"),
            vec![(0, "$ echo test")]
        );

        // Commands with output should not be flagged
        let block2 = vec!["$ echo test", "test"];
        assert!(rule.command_lines_without_output(&block2, "bash").is_empty());

        // No-output commands should not be flagged
        let block3 = vec!["$ cd /home"];
        assert!(rule.command_lines_without_output(&block3, "bash").is_empty());

        // Disabled rule should not flag
        let rule_disabled = MD014CommandsShowOutput::with_show_output(false);
        assert!(rule_disabled.command_lines_without_output(&block1, "bash").is_empty());

        // Non-shell language should not be flagged
        assert!(rule.command_lines_without_output(&block1, "python").is_empty());
    }

    #[test]
    fn test_edge_cases() {
        let rule = MD014CommandsShowOutput::new();
        // Bare $ doesn't match command pattern (needs a command after $)
        let content = "```bash\n$ \n```";
        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
        let result = rule.check(&ctx).unwrap();
        assert!(
            result.is_empty(),
            "Bare $ with only space doesn't match command pattern"
        );

        // Test empty code block
        let empty_content = "```bash\n```";
        let ctx2 = LintContext::new(empty_content, crate::config::MarkdownFlavor::Standard, None);
        let result2 = rule.check(&ctx2).unwrap();
        assert!(result2.is_empty(), "Empty code block should not be flagged");

        // Test minimal command
        let minimal = "```bash\n$ a\n```";
        let ctx3 = LintContext::new(minimal, crate::config::MarkdownFlavor::Standard, None);
        let result3 = rule.check(&ctx3).unwrap();
        assert_eq!(result3.len(), 1, "Minimal command should be flagged");
    }

    #[test]
    fn test_mixed_silent_and_output_commands() {
        let rule = MD014CommandsShowOutput::new();

        // Block with only silent commands should NOT be flagged
        let silent_only = "```bash\n$ cd /home\n$ mkdir test\n```";
        let ctx1 = LintContext::new(silent_only, crate::config::MarkdownFlavor::Standard, None);
        let result1 = rule.check(&ctx1).unwrap();
        assert!(
            result1.is_empty(),
            "Block with only silent commands should not be flagged"
        );

        // Block with silent commands followed by output-producing command
        // should flag the output-producing command only
        let mixed_silent_first = "```bash\n$ cd /home\n$ ls -la\n```";
        let ctx2 = LintContext::new(mixed_silent_first, crate::config::MarkdownFlavor::Standard, None);
        let result2 = rule.check(&ctx2).unwrap();
        assert_eq!(result2.len(), 1, "Only output-producing commands should be flagged");
        assert!(
            result2[0].message.contains("ls -la"),
            "Message should mention 'ls -la', not 'cd /home'. Got: {}",
            result2[0].message
        );

        // Block with mkdir followed by cat (which produces output)
        let mixed_mkdir_cat = "```bash\n$ mkdir test\n$ cat file.txt\n```";
        let ctx3 = LintContext::new(mixed_mkdir_cat, crate::config::MarkdownFlavor::Standard, None);
        let result3 = rule.check(&ctx3).unwrap();
        assert_eq!(result3.len(), 1, "Only output-producing commands should be flagged");
        assert!(
            result3[0].message.contains("cat file.txt"),
            "Message should mention 'cat file.txt', not 'mkdir'. Got: {}",
            result3[0].message
        );

        // Block with silent command followed by pip install (which produces output)
        let mkdir_pip = "```bash\n$ mkdir test\n$ pip install something\n```";
        let ctx3b = LintContext::new(mkdir_pip, crate::config::MarkdownFlavor::Standard, None);
        let result3b = rule.check(&ctx3b).unwrap();
        assert_eq!(result3b.len(), 1, "Block with pip install should be flagged");
        assert!(
            result3b[0].message.contains("pip install"),
            "Message should mention 'pip install'. Got: {}",
            result3b[0].message
        );

        // Block with output-producing command followed by silent command
        let mixed_output_first = "```bash\n$ echo hello\n$ cd /home\n```";
        let ctx4 = LintContext::new(mixed_output_first, crate::config::MarkdownFlavor::Standard, None);
        let result4 = rule.check(&ctx4).unwrap();
        assert_eq!(result4.len(), 1, "Only output-producing commands should be flagged");
        assert!(
            result4[0].message.contains("echo hello"),
            "Message should mention 'echo hello'. Got: {}",
            result4[0].message
        );
    }

    #[test]
    fn test_multiple_commands_without_output_all_flagged() {
        let rule = MD014CommandsShowOutput::new();

        // Two identical commands without output should produce two warnings
        let content = "```shell\n# First invocation\n$ my_command\n\n# Second invocation\n$ my_command\n```";
        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
        let result = rule.check(&ctx).unwrap();
        assert_eq!(result.len(), 2, "Both commands should be flagged. Got: {result:?}");
        assert!(result[0].message.contains("my_command"));
        assert!(result[1].message.contains("my_command"));
        // Verify they point to different lines
        assert_ne!(result[0].line, result[1].line, "Warnings should be on different lines");

        // Three different commands without output
        let content2 = "```bash\n$ echo hello\n$ ls -la\n$ pwd\n```";
        let ctx2 = LintContext::new(content2, crate::config::MarkdownFlavor::Standard, None);
        let result2 = rule.check(&ctx2).unwrap();
        assert_eq!(
            result2.len(),
            3,
            "All three commands should be flagged. Got: {result2:?}"
        );
        assert!(result2[0].message.contains("echo hello"));
        assert!(result2[1].message.contains("ls -la"));
        assert!(result2[2].message.contains("pwd"));

        // Two output-producing commands mixed with one silent command
        let content3 = "```bash\n$ echo hello\n$ cd /tmp\n$ ls -la\n```";
        let ctx3 = LintContext::new(content3, crate::config::MarkdownFlavor::Standard, None);
        let result3 = rule.check(&ctx3).unwrap();
        assert_eq!(
            result3.len(),
            2,
            "Only output-producing commands should be flagged. Got: {result3:?}"
        );
        assert!(result3[0].message.contains("echo hello"));
        assert!(result3[1].message.contains("ls -la"));
    }

    #[test]
    fn test_issue_516_exact_case() {
        let rule = MD014CommandsShowOutput::new();

        // Exact test case from GitHub issue #516
        let content = "---\ntitle: Heading\n---\n\nHere is a fenced code block:\n\n```shell\n# First invocation of my_command\n$ my_command\n\n# Second invocation of my_command\n$ my_command\n```\n";
        let ctx = LintContext::new(content, crate::config::MarkdownFlavor::Standard, None);
        let result = rule.check(&ctx).unwrap();
        assert_eq!(
            result.len(),
            2,
            "Both $ my_command lines should be flagged. Got: {result:?}"
        );
        assert_eq!(result[0].line, 9, "First warning should be on line 9");
        assert_eq!(result[1].line, 12, "Second warning should be on line 12");
    }

    #[test]
    fn test_default_config_section() {
        let rule = MD014CommandsShowOutput::new();
        let config_section = rule.default_config_section();
        assert!(config_section.is_some());
        let (name, _value) = config_section.unwrap();
        assert_eq!(name, "MD014");
    }
}