argusf 0.1.0.dev0__py3-none-any.whl

argusf/analysis/rules/rulesets/rgus/rgus006_entry_statement.py

@@ -0,0 +1,67 @@
+from argusf.analysis.rule import Rule, RuleMetadata
+from argusf.analysis.rules.findings import build_statement_finding
+from argusf.analysis.rules.registry import register
+from argusf.ir.models import EntryStatement, Finding, Severity, SourceFile
+
+
+@register
+class NoEntryStatement(Rule):
+    """## What it does
+
+    Checks for use of `ENTRY` statements.
+
+    ## Why is this bad?
+
+    `ENTRY` adds an extra entry point partway through a subroutine or
+    function, so the same body serves several procedures with different
+    argument lists and, in functions, different result variables. Which
+    code executes and which arguments are defined depends on where control
+    entered, which makes the procedure very hard to reason about. `ENTRY`
+    has been obsolescent since Fortran 2008. Separate procedures sharing
+    code through a module express the same design explicitly.
+
+    ## Example
+
+    ```fortran
+          subroutine setup(n)
+          integer :: n, m
+          n = 1
+          return
+          entry teardown(m)
+          m = 0
+          end subroutine setup
+    ```
+
+    Use instead:
+
+    ```fortran
+          module lifecycle
+          contains
+          subroutine setup(n)
+          integer :: n
+          n = 1
+          end subroutine setup
+          subroutine teardown(m)
+          integer :: m
+          m = 0
+          end subroutine teardown
+          end module lifecycle
+    ```
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS006",
+        name="entry-statement",
+        message="Use of ENTRY statement detected",
+        description="Flags ENTRY statements, which create multiple entry points into one procedure.",
+        default_severity=Severity.MEDIUM,
+        suggestion="Split each entry point into its own procedure, sharing code via a module",
+    )
+
+    def check(self, source_file: SourceFile) -> list[Finding]:
+        return [
+            build_statement_finding(self.metadata, source_file, statement)
+            for unit in source_file.walk_units()
+            for statement in unit.statements
+            if isinstance(statement, EntryStatement)
+        ]

argusf/analysis/rules/rulesets/rgus/rgus007_pause_statement.py

@@ -0,0 +1,93 @@
+from argusf.analysis.rule import Rule, RuleMetadata
+from argusf.analysis.rules.findings import build_statement_finding
+from argusf.analysis.rules.registry import register
+from argusf.autofix.edits import deletion, replacement
+from argusf.autofix.models import Applicability, Fix
+from argusf.autofix.source import full_lines_span, span_fits
+from argusf.ir.models import Finding, PauseStatement, Severity, SourceFile
+
+
+@register
+class NoPauseStatement(Rule):
+    """## What it does
+
+    Checks for use of `PAUSE` statements.
+
+    ## Why is this bad?
+
+    `PAUSE` suspends execution until the operator resumes it, a relic of
+    batch operation. How (and whether) execution can be resumed is
+    processor dependent, batch and HPC environments have no operator to
+    resume anything, and the statement was deleted from the standard in
+    Fortran 95 — compilers accept it only as a legacy extension. An
+    explicit `WRITE`/`READ` pair makes the interaction visible and
+    portable.
+
+    ## Example
+
+    ```fortran
+          pause 'check the intermediate output'
+    ```
+
+    Use instead:
+
+    ```fortran
+          write (*, *) 'check the intermediate output; press Enter'
+          read (*, *)
+    ```
+
+    ## Fix safety
+
+    The fix deletes the `PAUSE` line (or substitutes `CONTINUE` when the
+    line also carries a statement label or further statements), so the
+    program no longer stops there. Removing a deliberate operator pause
+    changes runtime behaviour, so the fix is always marked unsafe.
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS007",
+        name="pause-statement",
+        message="Use of PAUSE statement detected",
+        description="Flags PAUSE statements, deleted from the standard in Fortran 95.",
+        default_severity=Severity.HIGH,
+        suggestion="Replace PAUSE with an explicit WRITE/READ prompt, or remove it",
+        fixable=True,
+    )
+
+    def check(self, source_file: SourceFile) -> list[Finding]:
+        return [
+            build_statement_finding(self.metadata, source_file, statement, fix=self._build_fix(source_file, statement))
+            for unit in source_file.walk_units()
+            for statement in unit.statements
+            if isinstance(statement, PauseStatement)
+        ]
+
+    def _build_fix(self, source_file: SourceFile, statement: PauseStatement) -> Fix | None:
+        """Build the PAUSE-removal fix, or None.
+
+        Unsafe either way: removing a PAUSE changes runtime behaviour
+        (the program no longer stops for the operator).
+        """
+        source = source_file.source
+        span = statement.span
+        if not span_fits(source, span):
+            return None
+        lines = full_lines_span(source, span)
+        before = source[lines.start_byte : span.start_byte].strip()
+        after = source[span.end_byte : lines.end_byte].strip()
+        if before or (after and not after.startswith(b"!")):
+            # The line carries more than the PAUSE — a statement label
+            # (possibly a GOTO target) before it, or further statements
+            # after a semicolon. Substitute CONTINUE so the line's other
+            # meaning stays intact. A trailing !-comment does not force
+            # this path: it describes the PAUSE and goes with it.
+            return Fix(
+                applicability=Applicability.UNSAFE,
+                edits=(replacement(span, "continue"),),
+                message="Replace `pause` with `continue`",
+            )
+        return Fix(
+            applicability=Applicability.UNSAFE,
+            edits=(deletion(lines),),
+            message="Remove `pause` statement",
+        )

argusf/analysis/rules/rulesets/rgus/rgus008_todo_comment.py

@@ -0,0 +1,100 @@
+import re
+from typing import TYPE_CHECKING
+
+from argusf.analysis.rule import ConfigurableRule, RuleMetadata
+from argusf.analysis.rules.registry import register
+from argusf.ir.models import Comment, Finding, Severity, SourceFile
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from argusf.config.models import LintConfig
+
+
+@register
+class TodoComment(ConfigurableRule):
+    """## What it does
+
+    Checks for comments that begin with a task tag (`TODO`, `FIXME` and
+    `XXX` by default).
+
+    ## Why is this bad?
+
+    Task tags mark work the author deferred: a missing edge case, a
+    known inaccuracy, a planned clean-up. Left in the code they rot
+    silently — nothing ensures the task is ever resolved, revisited, or
+    even seen again. Surfacing them keeps deferred work visible so it
+    can be resolved, or tracked somewhere with more accountability than
+    a comment.
+
+    ## Example
+
+    ```fortran
+          ! TODO: handle the singular matrix case
+          call invert(a)
+    ```
+
+    ## Options
+
+    - `lint.task_tags`
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS008",
+        name="todo-comment",
+        message="Comment contains a task tag",
+        description="Flags comments that begin with a configured task tag such as TODO or FIXME.",
+        default_severity=Severity.INFO,
+        suggestion="Resolve the task, or move it to an issue tracker and remove the comment",
+        preview=True,
+    )
+
+    def __init__(self) -> None:
+        """Construct the rule unconfigured.
+
+        The engine injects the resolved lint config via configure()
+        before any check() call.
+        """
+        self._pattern: re.Pattern[str] | None = None
+
+    def configure(self, config: LintConfig) -> None:
+        self._pattern = self._tag_pattern(config.task_tags)
+
+    def _tag_pattern(self, tags: Sequence[str]) -> re.Pattern[str] | None:
+        """Compile the task-tag match pattern, or None if disabled.
+
+        The tag must open the comment (any number of bangs, then
+        optional whitespace); prose that merely mentions a tag
+        mid-comment does not fire. The lookahead stops a tag matching
+        as the prefix of a longer word (TODO vs TODOS). Matching is
+        case-sensitive. An empty tag list disables the rule.
+        """
+        if not tags:
+            return None
+        alternation = "|".join(re.escape(tag) for tag in tags)
+        return re.compile(rf"^!+\s*({alternation})(?!\w)")
+
+    def check(self, source_file: SourceFile) -> list[Finding]:
+        pattern = self._pattern
+        if pattern is None:
+            return []
+        return [
+            self._build_finding(source_file, comment, match)
+            for comment in source_file.walk_comments()
+            if (match := pattern.match(comment.text)) is not None
+        ]
+
+    def _build_finding(self, source_file: SourceFile, comment: Comment, match: re.Match[str]) -> Finding:
+        tag = match.group(1)
+        span = comment.span
+        return Finding(
+            rule_id=self.metadata.id,
+            message=f"Comment contains task tag {tag}",
+            severity=self.metadata.default_severity,
+            file_path=source_file.file_path,
+            line=span.start_row,
+            column=span.start_col + match.start(1),
+            end_line=span.start_row,
+            end_column=span.start_col + match.end(1),
+            suggestion=self.metadata.suggestion,
+        )

argusf/analysis/rules/rulesets/rgus/rgus009_unsorted_use_statements.py

@@ -0,0 +1,258 @@
+from itertools import pairwise
+
+from argusf.analysis.rule import Rule, RuleMetadata
+from argusf.analysis.rules.registry import register
+from argusf.autofix.edits import replacement
+from argusf.autofix.models import Applicability, Fix
+from argusf.autofix.source import full_lines_span, line_indent, slice_of, span_between, span_fits
+from argusf.ir.models import Comment, Finding, Severity, SourceFile, Statement, UseStatement
+
+
+@register
+class UnsortedUseStatements(Rule):
+    """## What it does
+
+    Checks for blocks of consecutive `USE` statements that are not sorted
+    alphabetically by module name.
+
+    ## Why is this bad?
+
+    A unit's `USE` statements are its import list. Keeping each block
+    sorted makes a dependency findable at a glance, keeps diffs that add a
+    module small and conflict-free, and stops duplicate imports from
+    hiding. The order has no semantic meaning in Fortran, so sorting is
+    free.
+
+    Only runs of directly adjacent `USE` statements are compared; a blank
+    line or a comment line starts a new block, so deliberate grouping is
+    preserved (sort within your groups). Module names compare
+    case-insensitively, as Fortran itself treats them.
+
+    ## Example
+
+    ```fortran
+          use solver_mod
+          use kinds_mod
+    ```
+
+    Use instead:
+
+    ```fortran
+          use kinds_mod
+          use solver_mod
+    ```
+
+    ## Fix safety
+
+    The fix reorders whole lines (continuations and trailing comments move
+    with their statement) and never crosses a blank line, comment line, or
+    non-USE statement. A line holding several `;`-separated USE statements
+    is split so each statement gets its own line — `;` is a pure statement
+    separator, so the split is as semantically inert as the reordering.
+    Because `USE` order is semantically inert, the fix is safe. A shared
+    line carrying anything besides its USE statements and `;` separators
+    (a trailing comment, a statement label) is reported without a fix.
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS009",
+        name="unsorted-use-statements",
+        message="Block of USE statements is not sorted by module name",
+        description="Flags consecutive USE statements that are not sorted alphabetically by module name.",
+        default_severity=Severity.LOW,
+        suggestion="Sort the USE statements alphabetically by module name",
+        preview=True,  # Must survey how real codebases group their USE blocks first
+        fixable=True,
+    )
+
+    def check(self, source_file: SourceFile) -> list[Finding]:
+        return [
+            self._build_finding(source_file, run)
+            for unit in source_file.walk_units()
+            for run in self._use_runs(unit.statements)
+            if not self._is_sorted(run)
+        ]
+
+    def _use_runs(self, statements: list[Statement]) -> list[list[UseStatement]]:
+        """Group statements into runs of adjacent USE statements.
+
+        A run is a maximal sequence of USE statements on directly
+        adjacent lines — the unit of sorting. Statements arrive in
+        document order, so one pass suffices: each statement either
+        rides along, extends the current run, or ends it (and a USE
+        after a gap immediately starts the next one).
+        """
+        runs: list[list[UseStatement]] = []
+        current: list[UseStatement] = []
+        for statement in statements:
+            if self._is_trailing_comment(statement, current):
+                # `use m ! why`: the comment is a separate statement on
+                # the USE's own line. The whole line moves as one, so it
+                # neither breaks nor extends the run.
+                continue
+            if not self._extends_run(statement, current):
+                # Anything else ends the run: a non-USE statement, a
+                # comment on its own line, or a USE after a blank line
+                # (blank lines produce no statement, so they are visible
+                # only as a row gap).
+                if current:
+                    runs.append(current)
+                current = []
+            if isinstance(statement, UseStatement):
+                current.append(statement)
+        if current:
+            runs.append(current)
+        return runs
+
+    def _is_trailing_comment(self, statement: Statement, current: list[UseStatement]) -> bool:
+        return isinstance(statement, Comment) and bool(current) and statement.span.start_row == current[-1].span.end_row
+
+    def _extends_run(self, statement: Statement, current: list[UseStatement]) -> bool:
+        """Whether `statement` continues the current run.
+
+        True when it is a USE on the line directly below the run's last
+        line (or the run is empty and it starts one).
+        """
+        if not isinstance(statement, UseStatement):
+            return False
+        return not current or statement.span.start_row <= current[-1].span.end_row + 1
+
+    def _is_sorted(self, run: list[UseStatement]) -> bool:
+        return all(self._sort_key(a) <= self._sort_key(b) for a, b in pairwise(run))
+
+    def _sort_key(self, statement: UseStatement) -> str:
+        """The casefolded module name a block is sorted by.
+
+        Fortran names are case-insensitive, so comparison casefolds.
+        """
+        return statement.module_name.casefold()
+
+    def _build_finding(self, source_file: SourceFile, run: list[UseStatement]) -> Finding:
+        first, last = run[0], run[-1]
+        return Finding(
+            rule_id=self.metadata.id,
+            message=self.metadata.message,
+            severity=self.metadata.default_severity,
+            file_path=source_file.file_path,
+            line=first.span.start_row,
+            column=first.span.start_col,
+            end_line=last.span.end_row,
+            end_column=last.span.end_col,
+            suggestion=self.metadata.suggestion,
+            fix=self._build_fix(source_file, run),
+        )
+
+    def _build_fix(self, source_file: SourceFile, run: list[UseStatement]) -> Fix | None:
+        """Build the block-reordering fix for a run, or None.
+
+        One edit replacing the whole block with its statements
+        reordered, one per line. A statement alone on its line moves
+        with its whole line (trailing comments and continuation lines
+        travel with it); `;`-separated statements sharing a line are
+        split onto a line each.
+        """
+        source = source_file.source
+        if not span_fits(source, run[-1].span):
+            return None
+        pieces = self._pieces(source, run)
+        if pieces is None:
+            return None
+        # Stable sort: duplicate imports of the same module keep their
+        # document order.
+        pieces.sort(key=lambda piece: piece[0])
+        content = "".join(self._terminated(text) for _, text in pieces)
+        block = full_lines_span(source, span_between(source, run[0].span.start_byte, run[-1].span.end_byte))
+        if not slice_of(source, block).endswith(b"\n"):
+            # The block sat at end-of-file without a final newline; a pure
+            # reorder must preserve that, so drop the one _terminated added.
+            content = content.removesuffix("\n")
+        return Fix(
+            applicability=Applicability.SAFE,
+            edits=(replacement(block, content),),
+            message="Sort `use` statements",
+        )
+
+    def _pieces(self, source: bytes, run: list[UseStatement]) -> list[tuple[str, str]] | None:
+        """The (sort key, text) pairs the block is rebuilt from.
+
+        One per statement, or None when the block cannot be rebuilt
+        faithfully.
+        """
+        pieces: list[tuple[str, str]] = []
+        try:
+            for line_statements in self._statements_by_line(source, run):
+                if len(line_statements) == 1:
+                    pieces.append(self._whole_line(source, line_statements[0]))
+                elif self._splits_cleanly(source, line_statements):
+                    pieces.extend(self._split_line(source, line_statements))
+                else:
+                    # The shared line carries something besides its USE
+                    # statements and `;` separators (a trailing comment, a
+                    # statement label) that has no unambiguous home once
+                    # the line splits; report without a fix.
+                    return None
+        except UnicodeDecodeError:
+            # Moving lines we cannot decode risks mangling them; report
+            # without a fix.
+            return None
+        return pieces
+
+    def _statements_by_line(self, source: bytes, run: list[UseStatement]) -> list[list[UseStatement]]:
+        """Group the run's statements by physical line.
+
+        Statements whose whole-line extents overlap are `;`-separated
+        on a shared line and must be rewritten together.
+        """
+        groups: list[list[UseStatement]] = []
+        previous_line_end = 0
+        for statement in run:
+            line = full_lines_span(source, statement.span)
+            if groups and line.start_byte < previous_line_end:
+                groups[-1].append(statement)
+            else:
+                groups.append([statement])
+            previous_line_end = line.end_byte
+        return groups
+
+    def _whole_line(self, source: bytes, statement: UseStatement) -> tuple[str, str]:
+        """The (sort key, text) for a statement that owns its line(s).
+
+        It moves whole, so its trailing comment and continuation lines
+        travel with it.
+        """
+        return self._sort_key(statement), slice_of(source, full_lines_span(source, statement.span)).decode()
+
+    def _splits_cleanly(self, source: bytes, line_statements: list[UseStatement]) -> bool:
+        """Whether a shared line holds only USE statements and `;`.
+
+        Blanks out the statements' own bytes and checks that nothing
+        but `;` separators and whitespace remains.
+        """
+        lines = full_lines_span(
+            source, span_between(source, line_statements[0].span.start_byte, line_statements[-1].span.end_byte)
+        )
+        residue = bytearray(slice_of(source, lines))
+        for statement in line_statements:
+            start = statement.span.start_byte - lines.start_byte
+            end = statement.span.end_byte - lines.start_byte
+            residue[start:end] = b" " * (end - start)
+        return not residue.translate(None, delete=b" \t;\r\n")
+
+    def _split_line(self, source: bytes, line_statements: list[UseStatement]) -> list[tuple[str, str]]:
+        """Move each statement of a shared line onto its own line.
+
+        Each keeps the shared line's indentation.
+        """
+        indent = line_indent(source, line_statements[0].span.start_byte)
+        return [
+            (self._sort_key(statement), f"{indent}{slice_of(source, statement.span).decode()}")
+            for statement in line_statements
+        ]
+
+    def _terminated(self, line: str) -> str:
+        """Ensure `line` ends with a newline.
+
+        The block's last line may sit at end-of-file without one; once
+        it moves up it needs a newline.
+        """
+        return line if line.endswith("\n") else f"{line}\n"

argusf/analysis/rules/selection.py

@@ -0,0 +1,83 @@
+"""Resolving select/ignore selectors to a set of rule ids."""
+
+from typing import TYPE_CHECKING
+
+from argusf.analysis.rules import RuleRegistry
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+ALL_SELECTOR = "ALL"
+
+
+class UnknownRuleSelectorError(ValueError):
+    """Raised when a selector matches no known rule."""
+
+    def __init__(self, selector: str) -> None:
+        """Build the error for an unrecognised `selector`.
+
+        Args:
+            selector: The selector that matched no rule.
+        """
+        super().__init__(f"Unknown rule selector: {selector!r}")
+
+
+def _matches(selector: str, rule_id: str) -> bool:
+    return selector == ALL_SELECTOR or rule_id.startswith(selector)
+
+
+def _specificity(selector: str) -> int:
+    return 0 if selector == ALL_SELECTOR else len(selector)
+
+
+class RuleSelectionResolver:
+    """Resolves select/ignore selectors against known rule ids."""
+
+    def __init__(self, known_rule_ids: Iterable[str] | None = None) -> None:
+        """Bind the resolver to a set of known rule ids.
+
+        Args:
+            known_rule_ids: Rule ids to resolve against; defaults to
+                the registered rules. Passing an explicit iterable
+                keeps unit tests independent of the registry.
+        """
+        self._known_rule_ids = list(RuleRegistry.keys() if known_rule_ids is None else known_rule_ids)
+
+    def resolve(self, select: Iterable[str], ignore: Iterable[str]) -> set[str]:
+        """Return the rule ids enabled by `select` minus `ignore`.
+
+        Per rule, the most specific matching selector on each side
+        wins; on a tie, ignore beats select. ALL is least specific.
+
+        Args:
+            select: Enabling selectors (codes, prefixes, or ALL).
+            ignore: Disabling selectors, same forms.
+
+        Returns:
+            The set of enabled rule ids.
+
+        Raises:
+            UnknownRuleSelectorError: On a selector matching no known
+                rule.
+        """
+        select = list(select)
+        ignore = list(ignore)
+        self._validate(select)
+        self._validate(ignore)
+        return {rule_id for rule_id in self._known_rule_ids if self._is_selected(rule_id, select, ignore)}
+
+    def _validate(self, selectors: list[str]) -> None:
+        for selector in selectors:
+            if selector == ALL_SELECTOR:
+                continue
+            if not selector or not any(rule_id.startswith(selector) for rule_id in self._known_rule_ids):
+                raise UnknownRuleSelectorError(selector)
+
+    def _is_selected(self, rule_id: str, select: list[str], ignore: list[str]) -> bool:
+        # The most specific (longest) matching selector on each side
+        # decides; on a specificity tie, ignore takes precedence over
+        # select. ALL is the least specific selector. A rule matched by
+        # neither side is off.
+        best_select = max((_specificity(s) for s in select if _matches(s, rule_id)), default=-1)
+        best_ignore = max((_specificity(s) for s in ignore if _matches(s, rule_id)), default=-1)
+        return best_select > best_ignore