argusf 0.1.0.dev0__py3-none-any.whl

argusf/__init__.py

@@ -0,0 +1,3 @@
+"""Argusf: a static code analyzer for Fortran 90."""
+
+__version__ = "0.1.0"

argusf/analysis/__init__.py

@@ -0,0 +1,14 @@
+"""Rule-based analysis of parsed source into findings."""
+
+from .engine import AnalysisEngine
+from .rule import Rule, RuleMetadata
+from .rules import RuleRegistry
+from .suppression import SuppressionFilter
+
+__all__ = [
+    "AnalysisEngine",
+    "Rule",
+    "RuleMetadata",
+    "RuleRegistry",
+    "SuppressionFilter",
+]

argusf/analysis/engine.py

@@ -0,0 +1,100 @@
+"""The analysis engine: runs rules over a parsed source file."""
+
+import logging
+from typing import TYPE_CHECKING
+
+from argusf.analysis.rule import ConfigurableRule, Rule
+from argusf.analysis.rules import RuleRegistry
+from argusf.analysis.rules.selection import RuleSelectionResolver
+from argusf.analysis.syntax_errors import syntax_error_finding
+
+if TYPE_CHECKING:
+    from argusf.analysis.suppression import SuppressionFilter
+    from argusf.config.models import ArgusConfig
+    from argusf.ir.models import Finding, SourceFile
+
+logger = logging.getLogger(__name__)
+
+
+class AnalysisEngine:
+    """Runs the configured rules over a source file."""
+
+    def __init__(self, config: ArgusConfig, suppression_filter: SuppressionFilter) -> None:
+        """Build the engine's rule set from config.
+
+        Constructs every registered rule, configures the ones that
+        read settings, filters by select/ignore and preview, and
+        resolves which rules may attach fixes.
+
+        Args:
+            config: Resolved configuration; its lint section drives
+                rule selection and fixability.
+            suppression_filter: Filter applied to findings after the
+                rules run.
+        """
+        self._config = config.lint
+        self._suppression_filter = suppression_filter
+        rules: list[Rule] = []
+        for rule_cls in RuleRegistry.values():
+            rule = rule_cls()
+            if isinstance(rule, ConfigurableRule):
+                rule.configure(self._config)
+            rules.append(rule)
+        self._rules = self._filter_rules(rules)
+        # A rule's fix survives only if the rule declares itself fixable
+        # (metadata is authoritative) AND the fixable/unfixable
+        # selectors resolve it in.
+        declared_fixable = {rule.metadata.id for rule in rules if rule.metadata.fixable}
+        self._fixable = declared_fixable & RuleSelectionResolver().resolve(
+            [*self._config.fixable, *self._config.extend_fixable], self._config.unfixable
+        )
+
+    def analyse(self, source_file: SourceFile) -> list[Finding]:
+        """Produce all findings for a parsed source file.
+
+        Seeds syntax-error findings from the parser, runs each enabled
+        rule, strips fixes from rules outside the fixable set, and
+        marks suppressed findings.
+
+        Args:
+            source_file: The parsed file to analyse.
+
+        Returns:
+            Findings in document order, some flagged suppressed.
+        """
+        # Syntax errors precede rule findings; they come from the
+        # parser, not a rule, so rule selection never applies to them.
+        findings: list[Finding] = [
+            syntax_error_finding(source_file.file_path, span) for span in source_file.syntax_errors
+        ]
+        for rule in self._rules:
+            rule_findings = rule.check(source_file)
+            if rule_findings:
+                logger.debug(
+                    "%s: %d finding(s) from %s",
+                    source_file.file_path,
+                    len(rule_findings),
+                    rule.metadata.id,
+                )
+                findings.extend(rule_findings)
+
+        # Strip fixes for rules outside the resolved fixable set before
+        # findings are cached or reported, so a finding's payload always
+        # matches what fixable/unfixable said at analysis time — an
+        # unfixable rule's findings carry no fix anywhere, including the
+        # JSON report's `fix: null`.
+        for finding in findings:
+            if finding.fix is not None and finding.rule_id not in self._fixable:
+                finding.fix = None
+
+        self._suppression_filter.apply(source_file, findings)
+        return findings
+
+    def _filter_rules(self, rules: list[Rule]) -> list[Rule]:
+        select = [*self._config.select, *self._config.extend_select]
+        enabled = RuleSelectionResolver().resolve(select, self._config.ignore)
+        return [
+            rule
+            for rule in rules
+            if rule.metadata.id in enabled and (self._config.preview or not rule.metadata.preview)
+        ]

argusf/analysis/rule.py

@@ -0,0 +1,45 @@
+"""Rule protocols and the metadata attached to each rule."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from argusf.config.models import LintConfig
+    from argusf.ir.models import Finding, Severity, SourceFile
+
+
+@dataclass(frozen=True)
+class RuleMetadata:
+    """Static metadata describing a rule."""
+
+    id: str
+    name: str
+    message: str
+    description: str
+    default_severity: Severity
+    suggestion: str | None = None
+    preview: bool = False
+    # The fixable-rule contract. A rule that offers fixes declares it
+    # here and must document the classification in a `## Fix safety`
+    # docstring section (a registry test enforces both directions). The
+    # declaration is authoritative: the engine strips fixes from any
+    # rule that does not make it, so an undeclared fix can never reach a
+    # report, the cache, or a file.
+    fixable: bool = False
+
+
+class Rule(Protocol):
+    """A lint rule: metadata plus a check over a source file."""
+
+    metadata: RuleMetadata
+
+    def check(self, source_file: SourceFile) -> list[Finding]:
+        """Return the findings this rule detects in `source_file`."""
+
+
+@runtime_checkable
+class ConfigurableRule(Rule, Protocol):
+    """A rule that reads lint settings via `configure`."""
+
+    def configure(self, config: LintConfig) -> None:
+        """Receive the resolved lint config before analysis."""

argusf/analysis/rules/__init__.py

@@ -0,0 +1,5 @@
+# Import rulesets to trigger registration of the built-in rules.
+from . import rulesets
+from .registry import RuleRegistry, register
+
+__all__ = ["RuleRegistry", "register", "rulesets"]

argusf/analysis/rules/documentation.py

@@ -0,0 +1,30 @@
+"""Rendering a rule's long-form documentation for the CLI."""
+
+import inspect
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from argusf.analysis.rule import Rule
+
+
+class RuleDocumentationRenderer:
+    """Renders a rule's docstring for the `argusf rule` command."""
+
+    def render(self, rule_cls: type[Rule]) -> str:
+        """Render a rule's documentation as markdown.
+
+        Uses the rule class's own docstring, falling back to its
+        metadata description when it has none.
+
+        Args:
+            rule_cls: The rule class to document.
+
+        Returns:
+            A markdown document with a heading, severity, and body.
+        """
+        metadata = rule_cls.metadata
+        # Read __doc__ rather than inspect.getdoc(): getdoc walks the
+        # MRO and would surface an inherited docstring for an
+        # undocumented rule.
+        documentation = inspect.cleandoc(rule_cls.__doc__) if rule_cls.__doc__ else metadata.description
+        return f"# {metadata.name} ({metadata.id})\n\nDefault severity: {metadata.default_severity}\n\n{documentation}"

argusf/analysis/rules/findings.py

@@ -0,0 +1,67 @@
+"""Shared finding constructors used by rules."""
+
+from typing import TYPE_CHECKING
+
+from argusf.ir.models import Finding, ProgramUnit, SourceFile, Statement
+
+if TYPE_CHECKING:
+    from argusf.analysis.rule import RuleMetadata
+    from argusf.autofix.models import Fix
+
+
+def build_statement_finding(
+    metadata: RuleMetadata, source_file: SourceFile, statement: Statement, fix: Fix | None = None
+) -> Finding:
+    """Build a finding anchored on a statement's span.
+
+    Args:
+        metadata: The reporting rule's metadata.
+        source_file: File the statement belongs to.
+        statement: Statement the finding points at.
+        fix: Optional fix to attach.
+
+    Returns:
+        A finding located at the statement.
+    """
+    return Finding(
+        rule_id=metadata.id,
+        message=metadata.message,
+        severity=metadata.default_severity,
+        file_path=source_file.file_path,
+        line=statement.span.start_row,
+        column=statement.span.start_col,
+        end_line=statement.span.end_row,
+        end_column=statement.span.end_col,
+        suggestion=metadata.suggestion,
+        fix=fix,
+    )
+
+
+def build_unit_finding(
+    metadata: RuleMetadata, source_file: SourceFile, unit: ProgramUnit, fix: Fix | None = None
+) -> Finding:
+    """Build a finding anchored on a program unit's first line.
+
+    Anchoring on the first line (rather than the whole unit) keeps the
+    report and inline suppressions on the declaration statement,
+    instead of underlining the entire body.
+
+    Args:
+        metadata: The reporting rule's metadata.
+        source_file: File the unit belongs to.
+        unit: Program unit the finding points at.
+        fix: Optional fix to attach.
+
+    Returns:
+        A finding located at the unit's declaration line.
+    """
+    return Finding(
+        rule_id=metadata.id,
+        message=metadata.message,
+        severity=metadata.default_severity,
+        file_path=source_file.file_path,
+        line=unit.span.start_row,
+        column=unit.span.start_col,
+        suggestion=metadata.suggestion,
+        fix=fix,
+    )

argusf/analysis/rules/registry.py

@@ -0,0 +1,22 @@
+"""The rule registry and its id-aware `register` decorator."""
+
+from argusf.analysis.rule import Rule
+from argusf.registry import Registry
+
+RuleRegistry: Registry[str, type[Rule]] = Registry()
+
+
+def register[T: type[Rule]](cls: T) -> T:
+    """Register a rule class under its metadata id.
+
+    A thin wrapper over the registry's own decorator that reads the id
+    from ``cls.metadata``, so it need not be written a second time.
+
+    Args:
+        cls: The rule class to register.
+
+    Returns:
+        The same class, unchanged.
+    """
+    RuleRegistry.register(cls.metadata.id)(cls)
+    return cls

argusf/analysis/rules/rulesets/__init__.py

@@ -0,0 +1,4 @@
+# Import rulesets to trigger rule registration with the registry.
+from . import rgus
+
+__all__ = ["rgus"]

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

@@ -0,0 +1,22 @@
+# Importing the rule modules registers each rule with the RuleRegistry.
+from .rgus001_no_goto import NoGoto
+from .rgus002_common_block import NoCommonBlock
+from .rgus003_equivalence import NoEquivalence
+from .rgus004_implicit_typing import ImplicitTyping
+from .rgus005_arithmetic_if import NoArithmeticIf
+from .rgus006_entry_statement import NoEntryStatement
+from .rgus007_pause_statement import NoPauseStatement
+from .rgus008_todo_comment import TodoComment
+from .rgus009_unsorted_use_statements import UnsortedUseStatements
+
+__all__ = [
+    "ImplicitTyping",
+    "NoArithmeticIf",
+    "NoCommonBlock",
+    "NoEntryStatement",
+    "NoEquivalence",
+    "NoGoto",
+    "NoPauseStatement",
+    "TodoComment",
+    "UnsortedUseStatements",
+]

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

@@ -0,0 +1,54 @@
+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 Finding, GotoStatement, Severity, SourceFile
+
+
+@register
+class NoGoto(Rule):
+    """## What it does
+
+    Checks for use of the `GO TO` statement.
+
+    ## Why is this bad?
+
+    `GO TO` jumps to a labelled statement unconditionally, so the flow of
+    control cannot be understood from the program's block structure alone.
+    Code that accumulates `GO TO` jumps degrades into paths that are hard
+    to follow, test, and modify. Fortran 90's structured constructs
+    (`DO`, `SELECT CASE`, `EXIT`, `CYCLE`) express the same logic without
+    labels.
+
+    ## Example
+
+    ```fortran
+          i = 0
+    10    continue
+          i = i + 1
+          if (i < 10) go to 10
+    ```
+
+    Use instead:
+
+    ```fortran
+          do i = 1, 10
+          end do
+    ```
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS001",
+        name="no-goto",
+        message="Use of GOTO statement detected",
+        description="Flags any use of GOTO, which hinders readability and structured control flow.",
+        default_severity=Severity.MEDIUM,
+        suggestion="Replace GOTO with structured control flow (DO, IF, EXIT)",
+    )
+
+    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, GotoStatement)
+        ]

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

@@ -0,0 +1,55 @@
+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 CommonStatement, Finding, Severity, SourceFile
+
+
+@register
+class NoCommonBlock(Rule):
+    """## What it does
+
+    Checks for use of `COMMON` blocks.
+
+    ## Why is this bad?
+
+    A `COMMON` block shares storage between program units by position
+    rather than by name: every declaration must repeat the block's layout,
+    and a mismatch in type, kind, or order silently corrupts data instead
+    of failing to compile. The result is implicit, untyped global state.
+    Module variables provide the same sharing with explicit names and
+    compiler-checked types.
+
+    ## Example
+
+    ```fortran
+          subroutine step()
+          common /state/ x, y
+          x = x + y
+          end subroutine step
+    ```
+
+    Use instead:
+
+    ```fortran
+          module state
+          real :: x, y
+          end module state
+    ```
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS002",
+        name="common-block",
+        message="Use of COMMON block detected",
+        description="Flags any use of COMMON blocks, which introduce implicit shared state.",
+        default_severity=Severity.MEDIUM,
+        suggestion="Replace COMMON block with MODULE variables",
+    )
+
+    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, CommonStatement)
+        ]

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

@@ -0,0 +1,55 @@
+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 EquivalenceStatement, Finding, Severity, SourceFile
+
+
+@register
+class NoEquivalence(Rule):
+    """## What it does
+
+    Checks for use of `EQUIVALENCE` statements.
+
+    ## Why is this bad?
+
+    `EQUIVALENCE` forces two or more variables to share the same storage,
+    creating hidden aliases: writing through one name silently changes the
+    value read through another, and the sharing is invisible at every use
+    site. It also defeats compiler optimisation and type checking. Modern
+    Fortran expresses the underlying intent directly — `TRANSFER` for type
+    reinterpretation, `POINTER` association for aliasing, allocatables or
+    derived types for storage reuse.
+
+    ## Example
+
+    ```fortran
+          real :: buffer(100)
+          integer :: ibuffer(100)
+          equivalence (buffer, ibuffer)
+    ```
+
+    Use instead:
+
+    ```fortran
+          real :: buffer(100)
+          integer :: ibuffer(100)
+          ibuffer = transfer(buffer, ibuffer)
+    ```
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS003",
+        name="equivalence",
+        message="Use of EQUIVALENCE statement detected",
+        description="Flags any use of EQUIVALENCE, which aliases storage between variables.",
+        default_severity=Severity.MEDIUM,
+        suggestion="Replace EQUIVALENCE with TRANSFER, POINTER association, or a derived type",
+    )
+
+    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, EquivalenceStatement)
+        ]

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

@@ -0,0 +1,129 @@
+from argusf.analysis.rule import Rule, RuleMetadata
+from argusf.analysis.rules.findings import build_unit_finding
+from argusf.analysis.rules.registry import register
+from argusf.autofix.edits import insertion
+from argusf.autofix.models import Applicability, Fix
+from argusf.autofix.source import line_end, line_indent, span_fits
+from argusf.ir.models import Finding, ImplicitStatement, ProgramUnit, Severity, SourceFile, Submodule, UseStatement
+
+
+@register
+class ImplicitTyping(Rule):
+    """## What it does
+
+    Checks for program units that do not disable implicit typing with
+    `IMPLICIT NONE`.
+
+    ## Why is this bad?
+
+    Without `IMPLICIT NONE`, any undeclared name is implicitly typed from
+    its first letter (`I` to `N` integer, everything else real). A typo in a
+    variable name then compiles cleanly as a brand-new variable instead of
+    failing, which is a classic source of silent numerical bugs.
+
+    A unit is not flagged when a host scope in the same file already
+    declares `IMPLICIT NONE` (contained procedures inherit the host's
+    implicit rules). Submodules and the procedures they contain are never
+    flagged: their implicit rules come from the ancestor module, which
+    usually lives in another file. Note that `IMPLICIT NONE (EXTERNAL)`
+    does not disable implicit typing and so does not satisfy this rule.
+
+    ## Example
+
+    ```fortran
+          program simulate
+          total = 0.0
+          end program simulate
+    ```
+
+    Use instead:
+
+    ```fortran
+          program simulate
+          implicit none
+          real :: total
+          total = 0.0
+          end program simulate
+    ```
+
+    ## Fix safety
+
+    The fix inserts `IMPLICIT NONE` after the unit's USE statements. Any
+    name the unit was implicitly typing then becomes a compile error until
+    it is declared — deliberate, but it means the fixed code may not
+    compile as-is, so the fix is always marked unsafe.
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS004",
+        name="implicit-typing",
+        message="Program unit does not declare IMPLICIT NONE",
+        description="Flags program units without IMPLICIT NONE, which leaves undeclared names implicitly typed.",
+        default_severity=Severity.HIGH,
+        suggestion="Add IMPLICIT NONE to the unit's specification section",
+        preview=True,  # Must confirm rule is stable on nested units
+        fixable=True,
+    )
+
+    def check(self, source_file: SourceFile) -> list[Finding]:
+        findings: list[Finding] = []
+        for unit in source_file.program_units:
+            self._check_unit(unit, source_file, host_covered=False, findings=findings)
+        return findings
+
+    def _check_unit(
+        self, unit: ProgramUnit, source_file: SourceFile, *, host_covered: bool, findings: list[Finding]
+    ) -> None:
+        covered = host_covered or any(
+            isinstance(statement, ImplicitStatement) and statement.is_none for statement in unit.statements
+        )
+        # A submodule's implicit rules come from its ancestor module, which
+        # usually lives in another file: treat the whole subtree as covered
+        # rather than risk false positives.
+        if isinstance(unit, Submodule):
+            covered = True
+        elif not covered:
+            findings.append(
+                build_unit_finding(self.metadata, source_file, unit, fix=self._build_fix(source_file, unit))
+            )
+        for subunit in unit.subunits:
+            self._check_unit(subunit, source_file, host_covered=covered, findings=findings)
+
+    def _build_fix(self, source_file: SourceFile, unit: ProgramUnit) -> Fix | None:
+        """Build the `implicit none` insertion fix, or None.
+
+        Fortran's statement ordering puts USE statements before the
+        implicit part, so the insertion point is the line after the
+        last USE statement, or after the unit's declaration line when
+        there are none.
+        """
+        source = source_file.source
+        if not span_fits(source, unit.span):
+            return None
+        uses = [statement for statement in unit.statements if isinstance(statement, UseStatement)]
+        if uses:
+            last_use = max(uses, key=lambda statement: statement.span.end_byte)
+            anchor = line_end(source, max(last_use.span.start_byte, last_use.span.end_byte - 1))
+        else:
+            anchor = line_end(source, unit.span.start_byte)
+        indent = self._probe_indent(source, anchor, unit)
+        return Fix(
+            applicability=Applicability.UNSAFE,
+            edits=(insertion(source, anchor, f"{indent}implicit none\n"),),
+            message="Insert `implicit none`",
+        )
+
+    def _probe_indent(self, source: bytes, anchor: int, unit: ProgramUnit) -> str:
+        """Probe the indentation to give the inserted statement.
+
+        Matches the indentation of the first non-blank line after the
+        insertion point (the unit's own body style); falls back to the
+        declaration line.
+        """
+        offset = anchor
+        while offset < min(len(source), unit.span.end_byte):
+            end = line_end(source, offset)
+            if source[offset:end].strip():
+                return line_indent(source, offset)
+            offset = end
+        return line_indent(source, unit.span.start_byte)

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

@@ -0,0 +1,62 @@
+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 ArithmeticIfStatement, Finding, Severity, SourceFile
+
+
+@register
+class NoArithmeticIf(Rule):
+    """## What it does
+
+    Checks for use of the arithmetic `IF` statement.
+
+    ## Why is this bad?
+
+    The arithmetic `IF` — `IF (expr) 10, 20, 30` — branches to one of
+    three labels depending on the sign of the expression. It is a labelled
+    jump in disguise, with all of `GO TO`'s readability problems plus an
+    easily-misread three-way convention. It has been obsolescent since
+    Fortran 90 and was deleted from the standard in Fortran 2018. Block
+    `IF`/`ELSE IF` constructs express the same logic structurally.
+
+    ## Example
+
+    ```fortran
+          if (x) 10, 20, 30
+    10    y = -1.0
+          go to 40
+    20    y = 0.0
+          go to 40
+    30    y = 1.0
+    40    continue
+    ```
+
+    Use instead:
+
+    ```fortran
+          if (x < 0.0) then
+            y = -1.0
+          else if (x == 0.0) then
+            y = 0.0
+          else
+            y = 1.0
+          end if
+    ```
+    """
+
+    metadata = RuleMetadata(
+        id="RGUS005",
+        name="arithmetic-if",
+        message="Use of arithmetic IF statement detected",
+        description="Flags the three-way arithmetic IF, deleted from the standard in Fortran 2018.",
+        default_severity=Severity.MEDIUM,
+        suggestion="Replace arithmetic IF with an IF/ELSE IF construct",
+    )
+
+    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, ArithmeticIfStatement)
+        ]