mod eb_style

module eb_style

EasyBuild easyconfig style checks and mechanical line wrapping.

lint_style reports what upstream enforces, without needing eb:

  • E501 line length (120), the pycodestyle whitespace codes that eb --check-contrib turns on (E225, E226, E227, E228, E231), and E999 when the file is not valid Python;

  • the easyconfigs CI lint, flake8 --select F,W605,W291 --filename '*.eb' (F541, W605, W291);

  • the easyconfigs test-suite checks and reviewer conventions as EB_* rules (python -s, sanity_check_paths shape, local variable naming, redefined parameters, %/+ formatting, templates versus f-strings).

Each finding carries a Severity. Errors are what CI or the test suite fails on; warnings are review conventions. When eb is on PATH, lint_recipe_files also runs eb --check-contrib and merges its findings, but the local rules do not depend on it (it never reports F541).

Product content (which -D flags) is residual judgment. Wrapping long string assignments so each physical line is ≤120 is mechanical and must not burn residual-agent turns. The formatter rewrites long single-quoted or double-quoted assignments such as key = '…' and key += "…" into parenthesized adjacent string literals. It also wraps long # comment lines using the patterns maintainers use by hand. It does not rewrite f-strings or % formatting.

Variables

const EB_MAX_LINE: usize

EasyBuild / pycodestyle easyconfig max line length.

const REVIEW_COUNTED: &[&str]

Review-convention warnings that block clean when they are on a review line, under review_scope: "file", or on a line that was edited.

Functions

fn blocks_clean(finding: &StyleFinding) -> bool

True when a finding keeps a recipe from being clean: any error, and any finding of the formatting family whatever its severity, unless it is outside the review scope (info). An error is info only when the MCP lint found the same code on the same line text in the file before the edits (pre-existing) and no review line or file-wide scope covers it; error_free still reports it.

fn diff_scope_findings(base: &str, text: &str, review_lines: &[usize]) -> Vec<StyleFinding>

EB_DIFF_OUTSIDE_REVIEW / EB_DIFF_SOURCES_CHANGED findings for the change from base to text, with review_lines the anchored lines (in the old or the new numbering; both are tried).

fn findings_clean(findings: &[StyleFinding]) -> bool

True when no finding blocks clean: no error, no in-scope EB_FMT_* finding, and no EB_SHLIB_HARDCODED on a review line. Other warnings (EB_SHLIB_HARDCODED elsewhere, EB_DEP_DUPLICATE, …) do not.

fn findings_error_free(findings: &[StyleFinding]) -> bool

True when no finding is an error (what upstream CI would fail on).

fn format_style(text: &str) -> FormatStyleResult

Rewrite fixable long lines; leave other long lines intact (still reported).

fn format_style_file(path: &Path, out: Option<&Path>) -> Result<FormatStyleResult, StyleError>

Format a file in place (or write to out if set). Returns the format result.

fn hunks(old: &str, new: &str) -> Vec<Hunk>

Line hunks from old to new (longest common subsequence over lines).

fn is_formatting_code(code: &str) -> bool

True for the string-formatting family (EB_FMT_*: '%s' % x, '...' + SHLIB_EXT, missing f, derived or removed templates). These are what style reviews ask for, so a leftover one means the fix is not done even though CI would not fail on it.

fn line_is_mechanically_fixable(line: &str) -> bool

True when format_style rewrites this physical line.

fn lint_recipe_files(paths: &[&Path]) -> Result<RecipeLintReport, StyleError>

Lint recipe files and, when eb is on PATH, merge eb --check-contrib.

fn lint_recipe_files_against(paths: &[&Path], base: Option<&Path>) -> Result<RecipeLintReport, StyleError>

Like lint_recipe_files, comparing each recipe against base (the version the change started from). That turns on the diff-mode rules and scopes EB_FMT_* findings to lines that differ from the base.

fn lint_recipe_files_scoped(paths: &[&Path], scopes: &[RecipeScope]) -> Result<RecipeLintReport, StyleError>

Like lint_recipe_files, with one RecipeScope per path.

fn lint_recipe_files_with(paths: &[&Path], eb: Option<&Path>) -> Result<RecipeLintReport, StyleError>

Like lint_recipe_files, but eb selects the EasyBuild program.

None searches PATH for eb. A path runs that program even when eb is also installed, which is how tests inject a fake contribution check. A missing explicit path does not fall back to PATH.

fn lint_style(text: &str) -> Vec<StyleFinding>

Lint one easyconfig’s text.

Runs every local rule (see the module docs). A file that is not valid Python gets an E999 finding, and the token-based rules still run on it. This function does not invoke eb.

fn lint_style_with(text: &str, options: &LintOptions<'_>) -> Vec<StyleFinding>

Like lint_style, with a file name for messages and an optional base version (diff mode, which adds EB_FMT_TEMPLATE_REMOVED).

fn python_syntax_error(text: &str) -> Option<(usize, usize, String)>

Python syntax error for text, as line, column, and message, or None.

EasyBuild loads an easyconfig with exec, so a file that is not valid Python never gets as far as any other check.

fn review_item_findings(statuses: &[ReviewItemStatus]) -> Vec<StyleFinding>

EB_REVIEW_ITEM_OPEN (warning that blocks clean) for each open item.

fn review_item_status(base: &str, text: &str, items: &[ReviewItem], acknowledged: &[String]) -> Vec<ReviewItemStatus>

Status of each review item for the change from base (the file as first seen, the numbering the items use) to text. Ids in acknowledged were answered without a change (the caller says none was needed).

fn severity_for(code: &str) -> Severity

Severity of a finding code. Unknown codes (including eb codes) are errors.

fn valid_easyconfig_parameters(easyblock: Option<&str>) -> BTreeSet<String>

Valid top-level easyconfig parameter names for one recipe.

This is the generic EasyBuild vocabulary, optionally extended by generic-easyblock-specific keys when the recipe’s easyblock is known.

Enums

enum Severity

How much a finding matters upstream.

Error

CI, the easyconfigs test suite, or eb --check-contrib fails on it.

Warning

A review convention. Fix it in lines you touch; it does not fail CI.

enum StyleError

Why a style pass could not run.

Io(String)

The file could not be read or written.

Structs and Unions

struct CheckContribReport

Outcome of shelling out to eb --check-contrib.

ran: bool

True when the eb process started.

exit_code: Option<i32>

Process exit code when ran is true.

detail: String

Short status. A missing eb is reported here and is not a lint failure by itself.

struct FormatStyleResult

Result of a format pass.

text: String

The formatted source.

lines_rewritten: usize

Number of physical lines that were rewritten.

remaining: Vec<StyleFinding>

Style findings still present after format.

Wrapping only clears mechanical E501 lines. Every other finding, and long lines the formatter cannot rewrite, stay here.

struct Hunk

One changed region between two texts.

old_start: usize

1-based first line in the old text (the line after which lines were inserted when removed is empty).

removed: Vec<String>

Lines removed from the old text.

new_start: usize

1-based first line in the new text (the line after which lines were removed when added is empty).

added: Vec<String>

Lines added in the new text.

params: Vec<String>

Top-level easyconfig parameters the hunk touches, old and new side.

Implementations

impl Hunk

Functions

fn comment_only(&self) -> bool

True when every changed line is a comment or blank.

struct LintOptions<'a>

Inputs beyond the easyconfig text.

file_name: Option<&'a str>

File name used in messages that EasyBuild words with one (python -s, checksum count). Defaults to <easyconfig>.

base: Option<&'a str>

The version the change started from. Turns on the diff-mode rules: EB_FMT_TEMPLATE_REMOVED, EB_SANITY_ENTRY_REMOVED, EB_SANITY_PATHS_REMOVED and EB_EASYBLOCK_CHANGED.

scope_to_base: bool

Scope EB_FMT_* findings to lines that differ from base: findings on unchanged lines become info. Set when the caller passed the base explicitly. Without it (or without a base), only untouched %%(...)s-escaped % entries are info.

review_lines: &'a [usize]

Lines (1-based, in the linted file) the review is about. EB_FMT_* findings there always count against clean.

file_scope: bool

The caller passed review_scope: "file": the review is about the whole file, so a review-convention warning such as EB_SHLIB_HARDCODED counts on every line, not only on review_lines.

struct RecipeLintFile

One easyconfig after lint_recipe_files.

path: PathBuf

Path that was linted.

findings: Vec<StyleFinding>

Style findings for this file. Local checks come first; eb findings follow.

Implementations

impl RecipeLintFile

Functions

fn clean(&self) -> bool

True when this file has no error and no EB_FMT_* finding.

fn error_free(&self) -> bool

True when this file has no error-severity finding.

struct RecipeLintReport

Local style lint plus an optional eb --check-contrib merge.

files: Vec<RecipeLintFile>

One entry per input path, in request order.

check_contrib: CheckContribReport

Whether eb --check-contrib ran, and why it did not when it did not.

Implementations

impl RecipeLintReport

Functions

fn clean(&self) -> bool

True when no file has an error or an EB_FMT_* finding.

fn error_free(&self) -> bool

True when no file has an error-severity finding.

struct RecipeScope

Per-recipe review scope for lint_recipe_files_scoped.

base: Option<String>

Text of the version the change started from (diff-mode rules).

scope_to_base: bool

Scope EB_FMT_* findings to lines that differ from base.

review_lines: Vec<usize>

Lines the review is about; EB_FMT_* findings there always count.

file_scope: bool

review_scope: "file": EB_SHLIB_HARDCODED counts on every line.

struct ReviewItem

One review comment the fix has to answer, anchored in the file as first seen (1-based, inclusive).

id: String

Caller’s id for the comment (reported back as given).

line_start: usize

1-based first line of the comment in the file as first seen.

line_end: usize

1-based last line of the comment in the file as first seen.

suggestion: Option<String>

The comment’s suggestion block: None for a prose comment, Some("") for an empty suggestion (delete the anchored lines).

comment: String

The comment text, used only for the mentions_absent hint.

struct ReviewItemStatus

Whether the change from the first-seen file answers one review item.

id: String

The caller’s id for the comment.

line_start: usize

1-based first line of the comment in the file as first seen.

line_end: usize

1-based last line of the comment in the file as first seen.

status: &'static str

changed (a hunk touches the anchored lines), suggestion_applied, deleted, no_change_needed (acknowledged by the caller), or, while open: no_hunk, suggestion_missing, not_deleted.

open: bool

True while the comment still has no matching change.

missing: Vec<String>

Suggestion lines the file does not contain yet.

mentions_absent: Vec<String>

Backticked names from the comment that the file does not contain.

struct StyleFinding

One style finding.

line: usize

1-based line number.

column: usize

1-based column. For E501 this is EB_MAX_LINE + 1.

code: String

Finding code (E501, W291, F541, EB_FMT_PERCENT, …, or an eb code).

message: String

Human-readable description of the finding.

mechanical: bool

True when format_style can rewrite this line deterministically.

origin: String

Empty for eb-stack’s own checks. eb --check-contrib when merged.

severity: Severity

error when CI or the test suite fails on it, warning for review conventions.

info: bool

True for an EB_FMT_* finding outside the review scope: a line that is unchanged from the base, or (without a base) an untouched %%(...)s-escaped % entry; or for an error that was already in the file before the edits (pre-existing, see blocks_clean). Reported for information; it does not make the file unclean.

in_review: bool

True when the finding is on a line in review_lines, or (for EB_SHLIB_HARDCODED) when the review scope is the whole file or the line differs from the base. An EB_SHLIB_HARDCODED there is what the reviewer asked to change, so it blocks clean (proof v5 and v6: a hardcoded .so on a commented line was left because the warning “needs a change only if the review asks for one”, and in v6 because review_scope: "file" without review_lines never counted it).

Implementations

impl StyleFinding

Functions

fn e501(line: usize, len: usize, mechanical: bool) -> Self

A long-line finding for line, which is len characters.

Traits implemented

impl fmt::Display for StyleFinding