wowlab_tidy/languages/rust/rules/style/

padding.rs

#[cfg(test)]
use googletest::prelude::*;
use ra_ap_syntax::{
    AstNode, SyntaxKind, SyntaxNode, SyntaxToken, ast, syntax_editor::SyntaxEditor,
};

use crate::{AstCtx, Example, Violation};

const BLANK_LINE_NEWLINES: usize = 2;

#[rustfmt::skip]
const EXAMPLES: &[Example] = &[
    Example {
        label: "return has padding",
        code: "fn value(flag: bool) -> usize {\n    let value = 1;\n\n    return value;\n}",
        pass: true,
    },
    Example {
        label: "return needs padding",
        code: "fn value() -> usize {\n    let value = 1;\n    return value;\n}",
        pass: false,
    },
    Example {
        label: "first return is exempt",
        code: "fn value() -> usize {\n    return 1;\n}",
        pass: true,
    },
    Example {
        label: "tail expression has padding",
        code: "fn value() -> usize {\n    let value = 1;\n\n    value\n}",
        pass: true,
    },
    Example {
        label: "tail expression needs padding",
        code: "fn value() -> usize {\n    let value = 1;\n    value\n}",
        pass: false,
    },
    Example {
        label: "let run needs following padding",
        code: "fn run() {\n    let one = 1;\n    let two = 2;\n    consume(one, two);\n}",
        pass: false,
    },
    Example {
        label: "let run followed by padding",
        code: "fn run() {\n    let one = 1;\n    let two = 2;\n\n    consume(one, two);\n}",
        pass: true,
    },
    Example {
        label: "multiline control expression is padded",
        code: "fn run(flag: bool) {\n    prepare();\n\n    if flag {\n        work();\n    }\n\n    finish();\n}",
        pass: true,
    },
    Example {
        label: "multiline control expression needs padding before and after",
        code: "fn run(flag: bool) {\n    prepare();\n    if flag {\n        work();\n    }\n    finish();\n}",
        pass: false,
    },
    Example {
        label: "first and last multiline controls need only interior padding",
        code: "fn run(flag: bool) {\n    if flag {\n        work();\n    }\n\n    loop {\n        break;\n    }\n}",
        pass: true,
    },
    Example {
        label: "single-expression closure is exempt",
        code: "fn run() {\n    consume(|| { 1 });\n}",
        pass: true,
    },
    Example {
        label: "docref region keeps contiguous statements",
        code: "fn value() -> usize {\n    // docref:start padding-region\n    let value = 1;\n    return value;\n    // docref:end padding-region\n}",
        pass: true,
    },
    Example {
        label: "fix pads outside but not inside docref region",
        code: "fn value() -> usize {\n    let outside = 1;\n    consume(outside);\n    // docref:start padding-region\n    let value = 1;\n    return value;\n    // docref:end padding-region\n}",
        pass: false,
    },
    Example {
        label: "directive stays attached to multiline control",
        code: "fn run(flag: bool) {\n    let value = String::new();\n    // #t(rust_clone_in_loop) bounded control path\n    if flag {\n        consume(value.clone());\n    }\n}",
        pass: false,
    },
    Example {
        label: "directive stays attached to tail expression",
        code: "fn value() -> usize {\n    let value = 1;\n    // #t(rust_clone_in_loop) representative fixture\n    value\n}",
        pass: false,
    },
    Example {
        label: "block directive stays attached to loop",
        code: "fn run(values: &[String]) {\n    let mut copies = Vec::new();\n    // #t(block: rust_clone_in_loop) bounded fixture\n    for value in values {\n        copies.push(value.clone());\n    }\n}",
        pass: false,
    },
];

crate::ast_tree_rule!(
    padding,
    "Require blank-line padding between distinct statement groups.",
    "Consistent vertical separation makes control flow, setup runs, and tail values easier to scan.",
    Low,
    fix_padding,
);

#[derive(Clone)]
#[expect(
    clippy::struct_excessive_bools,
    reason = "padding decisions combine four independent syntax classifications"
)]
struct Entry {
    syntax: SyntaxNode,
    is_let: bool,
    is_return: bool,
    is_multiline_control: bool,
    is_tail: bool,
}

fn check_padding(ctx: &AstCtx<'_>) -> Vec<Violation> {
    let mut violations = Vec::new();
    let docref_regions = docref_regions(ctx);

    for list in ctx.nodes::<ast::StmtList>() {
        for entry in missing_gaps(ctx, &docref_regions, &list) {
            violations.push(ctx.violation(
                &list,
                format!("blank line required before {}", entry_label(&entry)),
            ));
        }
    }

    violations
}

fn entries(list: &ast::StmtList) -> Vec<Entry> {
    let mut entries: Vec<Entry> = list.statements().map(entry_from_stmt).collect();

    if let Some(tail) = list.tail_expr() {
        entries.push(Entry {
            is_multiline_control: is_multiline_control(&tail),
            syntax: tail.syntax().clone(),
            is_let: false,
            is_return: matches!(tail, ast::Expr::ReturnExpr(_)),
            is_tail: true,
        });
    }

    entries
}

#[expect(
    clippy::needless_pass_by_value,
    reason = "statement iterators yield owned facade nodes and this helper is used directly by Iterator::map"
)]
fn entry_from_stmt(statement: ast::Stmt) -> Entry {
    let is_let = matches!(statement, ast::Stmt::LetStmt(_));
    let expression = match &statement {
        ast::Stmt::ExprStmt(statement) => statement.expr(),
        _ => None,
    };

    Entry {
        syntax: statement.syntax().clone(),
        is_let,
        is_return: expression
            .as_ref()
            .is_some_and(|expr| matches!(expr, ast::Expr::ReturnExpr(_))),
        is_multiline_control: expression.as_ref().is_some_and(is_multiline_control),
        is_tail: false,
    }
}

fn is_multiline_control(expression: &ast::Expr) -> bool {
    matches!(
        expression,
        ast::Expr::IfExpr(_)
            | ast::Expr::MatchExpr(_)
            | ast::Expr::ForExpr(_)
            | ast::Expr::WhileExpr(_)
            | ast::Expr::LoopExpr(_)
    ) && expression.syntax().text().contains_char('\n')
}

fn docref_regions(ctx: &AstCtx<'_>) -> Vec<(usize, usize)> {
    let mut regions = Vec::new();
    let mut open = None;

    for (index, line) in ctx.file.lines.iter().enumerate() {
        let Some(content) = crate::infra::parse::prose_comment_content(line) else {
            continue;
        };
        let marker = content.trim();

        if let Some(id) = marker.strip_prefix("docref:start ") {
            open = Some((id.trim(), index));
        } else if let Some(id) = marker.strip_prefix("docref:end ")
            && let Some((open_id, start)) = open.take()
            && open_id == id.trim()
        {
            regions.push((start, index));
        }
    }

    regions
}

fn gap_is_inside_docref(ctx: &AstCtx<'_>, regions: &[(usize, usize)], token: &SyntaxToken) -> bool {
    let line = ctx.line_index.line_col(token.text_range().start()).line as usize;

    regions
        .iter()
        .any(|&(start, end)| (start..end).contains(&line))
}

fn is_attached_directive(token: &SyntaxToken) -> bool {
    token.kind() == SyntaxKind::COMMENT
        && matches!(
            crate::infra::parse::directive(token.text()),
            Some(crate::infra::parse::DirectiveResult::Valid(directive))
                if matches!(
                    directive.scope,
                    crate::infra::parse::Scope::NextLine | crate::infra::parse::Scope::Block
                )
        )
}

fn padding_gap_token(current: &SyntaxNode) -> Option<SyntaxToken> {
    let mut gap = gap_token(current)?;

    while !has_blank_line(&gap) {
        let Some(comment) = gap.prev_token().filter(is_attached_directive) else {
            break;
        };
        let Some(previous_gap) = comment
            .prev_token()
            .filter(|token| token.kind() == SyntaxKind::WHITESPACE)
        else {
            break;
        };

        gap = previous_gap;
    }

    Some(gap)
}

// #t(fn: rust_unchecked_indexing) enumeration skips index zero before reading the preceding entry
fn missing_gaps(
    ctx: &AstCtx<'_>,
    docref_regions: &[(usize, usize)],
    list: &ast::StmtList,
) -> Vec<Entry> {
    let entries = entries(list);

    entries
        .iter()
        .enumerate()
        .skip(1)
        .filter(|(index, current)| {
            let previous = &entries[index - 1];
            let required = current.is_return
                || current.is_tail
                || (previous.is_let && !current.is_let)
                || current.is_multiline_control
                || previous.is_multiline_control;

            required
                && gap_token(&current.syntax).is_some_and(|immediate_gap| {
                    !gap_is_inside_docref(ctx, docref_regions, &immediate_gap)
                        && padding_gap_token(&current.syntax)
                            .is_some_and(|padding_gap| !has_blank_line(&padding_gap))
                })
        })
        .map(|(_, entry)| entry.clone())
        .collect()
}

fn gap_token(current: &SyntaxNode) -> Option<SyntaxToken> {
    current
        .prev_sibling_or_token()
        .and_then(ra_ap_syntax::NodeOrToken::into_token)
        .filter(|token| token.kind() == SyntaxKind::WHITESPACE)
}

fn has_blank_line(token: &SyntaxToken) -> bool {
    token.text().matches('\n').count() >= BLANK_LINE_NEWLINES
}

const fn entry_label(entry: &Entry) -> &'static str {
    if entry.is_return {
        "return statement"
    } else if entry.is_tail {
        "tail expression"
    } else if entry.is_multiline_control {
        "multi-line control-flow statement"
    } else {
        "statement following a let run"
    }
}

// #t(fn: rust_alloc_in_loop, rust_clone_in_loop) each missing whitespace boundary needs an owned replacement token
fn fix_padding(ctx: &AstCtx<'_>, _violations: &[Violation]) -> Option<String> {
    let (editor, root) = SyntaxEditor::with_ast_node(ctx.root);
    let docref_regions = docref_regions(ctx);
    let mut changed = false;

    for list in root.syntax().descendants().filter_map(ast::StmtList::cast) {
        for entry in missing_gaps(ctx, &docref_regions, &list) {
            let token = padding_gap_token(&entry.syntax)?;

            editor.replace(
                token.clone(),
                editor.make().whitespace(&format!("\n{}", token.text())),
            );
            changed = true;
        }
    }

    changed.then(|| editor.finish().new_root().to_string())
}

crate::tidy_ast_test!(check_padding, {
    crate::example_tests!(EXAMPLES, check_padding);
    crate::fix_tests!(ast_tree, check_padding, fix_padding);

    #[gtest]
    fn fix_preserves_contiguous_docref_region() -> Result<()> {
        let source = "fn value() -> usize {\n    let outside = 1;\n    consume(outside);\n    // docref:start padding-region\n    let value = 1;\n    return value;\n    // docref:end padding-region\n}";
        let expected = "fn value() -> usize {\n    let outside = 1;\n\n    consume(outside);\n    // docref:start padding-region\n    let value = 1;\n    return value;\n    // docref:end padding-region\n}";

        verify_eq!(
            crate::apply_ast_tree_fix(source, check_padding, fix_padding),
            expected
        )?;

        Ok(())
    }

    #[gtest]
    fn fix_places_padding_before_attached_directives() -> Result<()> {
        let cases = [
            (
                "fn run(flag: bool) {\n    let value = String::new();\n    // #t(rust_clone_in_loop) bounded control path\n    if flag {\n        consume(value.clone());\n    }\n}",
                "fn run(flag: bool) {\n    let value = String::new();\n\n    // #t(rust_clone_in_loop) bounded control path\n    if flag {\n        consume(value.clone());\n    }\n}",
            ),
            (
                "fn value() -> usize {\n    let value = 1;\n    // #t(rust_clone_in_loop) representative fixture\n    value\n}",
                "fn value() -> usize {\n    let value = 1;\n\n    // #t(rust_clone_in_loop) representative fixture\n    value\n}",
            ),
            (
                "fn run(values: &[String]) {\n    let mut copies = Vec::new();\n    // #t(block: rust_clone_in_loop) bounded fixture\n    for value in values {\n        copies.push(value.clone());\n    }\n}",
                "fn run(values: &[String]) {\n    let mut copies = Vec::new();\n\n    // #t(block: rust_clone_in_loop) bounded fixture\n    for value in values {\n        copies.push(value.clone());\n    }\n}",
            ),
        ];

        for (source, expected) in cases {
            verify_eq!(
                crate::apply_ast_tree_fix(source, check_padding, fix_padding),
                expected
            )?;
        }

        Ok(())
    }
});