argusf 0.1.0.dev0__py3-none-any.whl

argusf/discovery/gitignore.py

@@ -0,0 +1,125 @@
+"""Matching paths against `.gitignore` files during discovery."""
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+import pathspec
+
+from argusf.discovery.repo import find_repo_root
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.diagnostics import Diagnostics
+
+
+@runtime_checkable
+class GitignoreMatcher(Protocol):
+    """Decides whether discovery should ignore a walked path.
+
+    Implementations back the `respect_gitignore` setting: the real
+    matcher consults `.gitignore` files, the null matcher ignores
+    nothing.
+    """
+
+    def is_ignored(self, directory: Path, name: str, *, is_dir: bool) -> bool:
+        """Report whether `name` under `directory` is gitignored.
+
+        Args:
+            directory: Absolute directory holding the entry.
+            name: Basename of the file or directory being tested.
+            is_dir: Whether `name` is a directory; directory-only
+                patterns such as `build/` match only when true.
+
+        Returns:
+            True if the entry should be skipped during discovery.
+        """
+
+
+class NullGitignoreMatcher(GitignoreMatcher):
+    """Used when respect_gitignore is off — nothing is ever ignored."""
+
+    def is_ignored(self, directory: Path, name: str, *, is_dir: bool) -> bool:  # noqa: ARG002 - null object ignores nothing
+        """Ignore nothing — every path clears the gitignore check.
+
+        Returns:
+            Always False.
+        """
+        return False
+
+
+class PathspecGitignoreMatcher(GitignoreMatcher):
+    """Matches paths against nested `.gitignore` files, git-style.
+
+    `directory` arguments must be absolute so they are comparable
+    with the boundary computed from the walk root.
+    """
+
+    def __init__(self, root: Path, diagnostics: Diagnostics) -> None:
+        """Bound the matcher to the walk root's repository.
+
+        Git only honours .gitignore files inside the repository, so
+        those between the walk root and the repo root still apply;
+        outside a repository nothing above the walk root is consulted,
+        or a stray ~/.gitignore could change results.
+
+        Args:
+            root: Directory the discovery walk starts from.
+            diagnostics: Channel for reporting unreadable
+                `.gitignore` files.
+        """
+        self._diagnostics = diagnostics
+        self._boundary = find_repo_root(root.absolute()) or root.absolute()
+        self._specs: dict[Path, pathspec.GitIgnoreSpec | None] = {}
+
+    def is_ignored(self, directory: Path, name: str, *, is_dir: bool) -> bool:
+        """Report whether `name` under `directory` is gitignored.
+
+        Ascends from `directory` to the boundary (repo root, or the
+        walk root outside a repo), consulting each `.gitignore` along
+        the way. The deepest file wins, so a child `!pattern`
+        negation can re-include what a parent ignored; the ascent
+        stops as soon as a file decides the path either way.
+
+        Args:
+            directory: Absolute directory holding the entry.
+            name: Basename of the file or directory being tested.
+            is_dir: Whether `name` is a directory; directory-only
+                patterns such as `build/` match only when true.
+
+        Returns:
+            True if some `.gitignore` ignores the entry and no
+            deeper negation re-includes it.
+        """
+        path = directory / name
+        current = directory
+        while True:
+            spec = self._spec_for(current)
+            if spec is not None:
+                relative = str(path.relative_to(current))
+                # Directory-only patterns ("build/") only match paths
+                # presented with a trailing slash.
+                result = spec.check_file(f"{relative}/" if is_dir else relative)
+                if result.include is not None:
+                    # Deepest .gitignore wins. include=False means a
+                    # "!pattern" negation re-included the path,
+                    # overriding any shallower ignore — so stop
+                    # ascending either way.
+                    return result.include
+            if current == self._boundary:
+                return False
+            current = current.parent
+
+    def _spec_for(self, directory: Path) -> pathspec.GitIgnoreSpec | None:
+        if directory not in self._specs:
+            self._specs[directory] = self._load(directory / ".gitignore")
+        return self._specs[directory]
+
+    def _load(self, gitignore: Path) -> pathspec.GitIgnoreSpec | None:
+        try:
+            lines = gitignore.read_text(encoding="utf-8").splitlines()
+        except FileNotFoundError:
+            return None
+        except OSError, UnicodeDecodeError:
+            self._diagnostics.emit(f"could not read {gitignore}, ignoring it")
+            return None
+        return pathspec.GitIgnoreSpec.from_lines(lines)

argusf/discovery/repo.py

@@ -0,0 +1,30 @@
+"""Locating the repository root that bounds discovery searches."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def find_repo_root(start: Path) -> Path | None:
+    """Find the nearest ancestor directory holding a `.git` entry.
+
+    Searches `start` and each of its parents, closest first, and
+    returns the first directory that contains a `.git` entry. Existence
+    is the test, not is_dir, since `.git` may be a file (worktrees,
+    submodules). The walk is finite (Path.parents ends at the
+    filesystem root), so it terminates even outside a repository. This
+    is the boundary at which upward searches for config files and
+    `.gitignore` files stop.
+
+    Args:
+        start: Directory to begin the upward search from.
+
+    Returns:
+        The repository root, or None when no ancestor contains a
+        `.git` entry (i.e. `start` is not inside a repository).
+    """
+    for candidate in (start, *start.parents):
+        if (candidate / ".git").exists():
+            return candidate
+    return None

argusf/hashing/__init__.py

@@ -0,0 +1,5 @@
+"""Content and cache-version hashing."""
+
+from .hash import HashBackend, Hasher
+
+__all__ = ["HashBackend", "Hasher"]

argusf/hashing/hash.py

@@ -0,0 +1,48 @@
+"""SHA256 hashing for content identity and cache versioning."""
+
+import hashlib
+from typing import Protocol
+
+
+class Hasher(Protocol):
+    """Hashes bytes for content identity and cache versioning.
+
+    Injected into the file collector (per-file content hashing) and
+    the cache (naming the versioned cache subdirectory).
+    """
+
+    def hash_bytes(self, content: bytes) -> str:
+        """Return a stable hex digest of `content`.
+
+        Args:
+            content: Raw file bytes to hash.
+
+        Returns:
+            Hex digest identifying the content.
+        """
+
+    def get_cache_version_hash(self, argus_version: str, python_version: str, settings_fingerprint: str) -> str:
+        """Return the cache-version key for the given inputs.
+
+        Args:
+            argus_version: Running argusf version.
+            python_version: Running Python version.
+            settings_fingerprint: Fingerprint of the resolved lint
+                config.
+
+        Returns:
+            Hex digest naming the cache subdirectory; changing any
+            input invalidates previously cached findings.
+        """
+
+
+class HashBackend(Hasher):
+    """SHA256 implementation of `Hasher`."""
+
+    def hash_bytes(self, content: bytes) -> str:
+        """Return the SHA256 hex digest of `content`."""
+        return hashlib.sha256(content).hexdigest()
+
+    def get_cache_version_hash(self, argus_version: str, python_version: str, settings_fingerprint: str) -> str:
+        """Return the SHA256 digest of the concatenated inputs."""
+        return hashlib.sha256(f"{argus_version}{python_version}{settings_fingerprint}".encode()).hexdigest()

argusf/ir/__init__.py

@@ -0,0 +1 @@
+"""Intermediate representation of parsed source and findings."""

argusf/ir/models/__init__.py

@@ -0,0 +1,49 @@
+from .findings import Finding, RunResult, Severity
+from .source import (
+    ArithmeticIfStatement,
+    BlockData,
+    Comment,
+    CommonStatement,
+    EntryStatement,
+    EquivalenceStatement,
+    Function,
+    GotoStatement,
+    ImplicitStatement,
+    Module,
+    PauseStatement,
+    Program,
+    ProgramUnit,
+    SourceFile,
+    SourceFileMetadata,
+    SourceSpan,
+    Statement,
+    Submodule,
+    Subroutine,
+    UseStatement,
+)
+
+__all__ = [
+    "ArithmeticIfStatement",
+    "BlockData",
+    "Comment",
+    "CommonStatement",
+    "EntryStatement",
+    "EquivalenceStatement",
+    "Finding",
+    "Function",
+    "GotoStatement",
+    "ImplicitStatement",
+    "Module",
+    "PauseStatement",
+    "Program",
+    "ProgramUnit",
+    "RunResult",
+    "Severity",
+    "SourceFile",
+    "SourceFileMetadata",
+    "SourceSpan",
+    "Statement",
+    "Submodule",
+    "Subroutine",
+    "UseStatement",
+]

argusf/ir/models/findings.py

@@ -0,0 +1,74 @@
+"""IR models for findings and the aggregate outcome of a run."""
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections import Counter
+    from pathlib import Path
+
+    from argusf.autofix.models import Fix
+    from argusf.ir.models.source import SourceFileMetadata
+
+
+class Severity(StrEnum):
+    """Severity level of a finding."""
+
+    ERROR = "error"
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+@dataclass
+class Finding:
+    """A single issue found in a source file."""
+
+    rule_id: str
+    message: str
+    severity: Severity
+    file_path: Path
+    line: int
+    column: int | None = None
+    end_line: int | None = None
+    end_column: int | None = None
+    suggestion: str | None = None
+    # None either because the rule offers no fix or because the engine
+    # stripped it (rule outside the resolved fixable set) — cached
+    # findings then match what is reported.
+    fix: Fix | None = None
+    suppressed: bool = False
+
+
+@dataclass
+class RunResult:
+    """Findings and counters produced by a single analysis run."""
+
+    findings: list[Finding] = field(default_factory=list)
+    failed_parse_files: list[SourceFileMetadata] = field(default_factory=list)
+    files_analysed: int = 0
+    files_from_cache: int = 0
+    elapsed: float = 0.0
+    # Fixes applied per file, counted per rule id; feeds the
+    # fixed/remaining summary and the --show-fixes enumeration.
+    fixed_by_file: dict[Path, Counter[str]] = field(default_factory=dict)
+    # Rendered unified diffs per file, in discovery order (--diff mode
+    # only).
+    diffs: list[tuple[Path, str]] = field(default_factory=list)
+
+    @property
+    def total_files(self) -> int:
+        """Total files processed (freshly analysed plus cache hits)."""
+        return self.files_analysed + self.files_from_cache
+
+    @property
+    def fixed_count(self) -> int:
+        """Total number of fixes applied across all files."""
+        return sum(sum(counts.values()) for counts in self.fixed_by_file.values())
+
+    def active_findings(self) -> list[Finding]:
+        """Return the findings that were not suppressed."""
+        return [finding for finding in self.findings if not finding.suppressed]

argusf/ir/models/source.py

@@ -0,0 +1,199 @@
+"""IR models for source files and their parsed program structure."""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from pathlib import Path
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    """A region of source, in both byte and row/column coordinates."""
+
+    start_row: int
+    start_col: int
+    end_row: int
+    end_col: int
+    start_byte: int
+    end_byte: int
+
+
+@dataclass
+class Statement:
+    """Base class for a statement located by its source span."""
+
+    span: SourceSpan
+
+
+@dataclass
+class GotoStatement(Statement):
+    """A GOTO statement."""
+
+
+@dataclass
+class CommonStatement(Statement):
+    """A COMMON block statement."""
+
+
+@dataclass
+class Comment(Statement):
+    """A source comment and its text."""
+
+    text: str
+
+
+@dataclass
+class EquivalenceStatement(Statement):
+    """An EQUIVALENCE statement."""
+
+
+@dataclass
+class ArithmeticIfStatement(Statement):
+    """An arithmetic IF statement."""
+
+
+@dataclass
+class EntryStatement(Statement):
+    """An ENTRY statement."""
+
+
+@dataclass
+class PauseStatement(Statement):
+    """A PAUSE statement."""
+
+
+@dataclass
+class UseStatement(Statement):
+    """A USE statement, carrying the referenced module name."""
+
+    # The referenced module, as written (Fortran names are
+    # case-insensitive, so consumers comparing names must casefold). The
+    # span covers the whole statement including any ONLY clause and
+    # continuation lines.
+    module_name: str
+
+
+@dataclass
+class ImplicitStatement(Statement):
+    """An IMPLICIT statement; `is_none` disables implicit typing."""
+
+    # True when the statement disables implicit typing:
+    #   implicit none                  -> True
+    #   implicit none (type)           -> True
+    #   implicit none (type, external) -> True
+    #   implicit none (external)       -> False*
+    #   implicit real(a-h)             -> False
+    #
+    # * `implicit none (external)` only forbids implicit interfaces.
+    is_none: bool
+
+
+@dataclass
+class ProgramUnit:
+    """A program unit (program, module, procedure) and its body."""
+
+    span: SourceSpan
+    # None for anonymous units: Fortran allows a main program without a
+    # PROGRAM statement, which tree-sitter surfaces as a nameless node.
+    name: str | None = None
+    statements: list[Statement] = field(init=False, default_factory=list)
+    subunits: list[ProgramUnit] = field(init=False, default_factory=list)
+
+    def add_statement(self, statement: Statement) -> None:
+        """Append a statement to this unit's body."""
+        self.statements.append(statement)
+
+    def add_subunit(self, unit: ProgramUnit) -> None:
+        """Append a contained (nested) program unit."""
+        self.subunits.append(unit)
+
+
+@dataclass
+class Program(ProgramUnit):
+    """A main program unit."""
+
+
+@dataclass
+class Module(ProgramUnit):
+    """A module unit."""
+
+
+@dataclass
+class Subroutine(ProgramUnit):
+    """A subroutine unit."""
+
+
+@dataclass
+class Function(ProgramUnit):
+    """A function unit."""
+
+
+@dataclass
+class Submodule(ProgramUnit):
+    """A submodule unit."""
+
+
+@dataclass
+class BlockData(ProgramUnit):
+    """A BLOCK DATA unit."""
+
+
+@dataclass
+class SourceFileMetadata:
+    """A source file's identity: the cache lookup and validation key.
+
+    Deliberately lean — never carries file contents, so it can be stored
+    and compared freely. Consumers that need the bytes (the parser, the
+    fix stage) read the file themselves.
+    """
+
+    file_path: Path
+    size: int
+    mtime: float
+    content_hash: str
+
+
+@dataclass
+class SourceFile:
+    """A parsed source file: program units, comments, and raw bytes."""
+
+    file_path: Path
+    program_units: list[ProgramUnit] = field(default_factory=list)
+    # Comments outside any program unit (file headers, text between
+    # units); a comment inside a unit is a statement of that unit.
+    # Fortran permits no statements outside units, so comments are the
+    # only possible top-level content besides program units.
+    comments: list[Comment] = field(default_factory=list)
+    # Spans of unparseable regions (tree-sitter ERROR/missing nodes and
+    # units whose handler failed); each becomes a syntax-error finding.
+    syntax_errors: list[SourceSpan] = field(default_factory=list)
+    # The exact bytes the parse tree's spans index into. Rules need them
+    # to build fixes (line extraction, indentation); excluded from repr
+    # so file contents never leak into tracebacks/logs.
+    source: bytes = field(default=b"", repr=False)
+
+    def add_program_unit(self, unit: ProgramUnit) -> None:
+        """Append a top-level program unit."""
+        self.program_units.append(unit)
+
+    def add_comment(self, comment: Comment) -> None:
+        """Append a file-level comment."""
+        self.comments.append(comment)
+
+    def walk_units(self) -> Iterator[ProgramUnit]:
+        """Yield every program unit depth-first, subunits included."""
+        stack = list(reversed(self.program_units))
+        while stack:
+            unit = stack.pop()
+            yield unit
+            stack.extend(reversed(unit.subunits))
+
+    def walk_comments(self) -> Iterator[Comment]:
+        """Yield comments (file-level and unit) in document order."""
+        comments = list(self.comments)
+        for unit in self.walk_units():
+            comments.extend(statement for statement in unit.statements if isinstance(statement, Comment))
+        comments.sort(key=lambda comment: comment.span.start_byte)
+        yield from comments

argusf/orchestrator.py

@@ -0,0 +1,127 @@
+"""The Orchestrator: coordinates the per-file analysis pipeline."""
+
+import logging
+import time
+from typing import TYPE_CHECKING
+
+from argusf.analysis.syntax_errors import syntax_error_finding
+from argusf.ir.models import RunResult
+from argusf.parser.backend import ParseError, ParsingEngine
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.analysis.engine import AnalysisEngine
+    from argusf.autofix.engine import FixEngine
+    from argusf.cache.backend import Cacher
+    from argusf.config.models import ArgusConfig
+    from argusf.diagnostics import Diagnostics
+    from argusf.discovery.backend import FileCollector
+    from argusf.reporting import Reporter
+
+logger = logging.getLogger(__name__)
+
+
+class Orchestrator:
+    """Coordinates discovery, caching, analysis, fixing, reporting."""
+
+    def __init__(  # noqa: PLR0913
+        self,
+        file_collector: FileCollector,
+        parsing_engine: ParsingEngine,
+        analysis_engine: AnalysisEngine,
+        cache_backend: Cacher,
+        fix_engine: FixEngine,
+        diagnostics: Diagnostics,
+        reporter: Reporter,
+    ) -> None:
+        """Wire the orchestrator to its pipeline collaborators.
+
+        Args:
+            file_collector: Discovers and hashes source files.
+            parsing_engine: Parses files into IR.
+            analysis_engine: Produces findings for a parsed file.
+            cache_backend: Caches and restores per-file findings.
+            fix_engine: Runs the autofix stage per file.
+            diagnostics: Channel for parse-failure notices.
+            reporter: Writes the run's results.
+        """
+        self._file_collector = file_collector
+        self._parsing_engine = parsing_engine
+        self._analysis_engine = analysis_engine
+        self._cache_backend = cache_backend
+        self._fix_engine = fix_engine
+        self._diagnostics = diagnostics
+        self._reporter = reporter
+
+    def run(self, target: Path, config: ArgusConfig) -> RunResult:
+        """Run the full pipeline over a target and report results.
+
+        Streams each discovered file through cache lookup or analysis,
+        the fix stage, and caching, then writes the report.
+
+        Args:
+            target: File or directory to analyse.
+            config: Resolved configuration for the run.
+
+        Returns:
+            The aggregate run result.
+        """
+        start = time.perf_counter()
+        result = RunResult()
+
+        for file in self._file_collector.collect(target):
+            cached = None if config.no_cache else self._cache_backend.get(file)
+            if cached is not None:
+                # Counts where the initial findings came from. A cache
+                # hit that the fix stage later rewrites is deliberately
+                # not reclassified as analysed: the fix loop's in-memory
+                # re-analysis happens for freshly-analysed files too,
+                # without recounting them either.
+                result.files_from_cache += 1
+                findings = cached.findings
+                logger.debug("cache hit: %s", file.file_path)
+            else:
+                try:
+                    source_file = self._parsing_engine.parse(file)
+                except ParseError:
+                    # Near-dead with the tree-sitter engine (it records
+                    # error regions instead of raising), but any
+                    # ParsingEngine may still fail outright: the file
+                    # becomes one whole-file syntax-error finding and is
+                    # cached like any other. Never fixed — the fix stage
+                    # refuses syntax-error files anyway.
+                    self._diagnostics.emit(f"parse failed: {file.file_path}")
+                    result.failed_parse_files.append(file)
+                    findings = [syntax_error_finding(file.file_path, span=None)]
+                    result.findings.extend(findings)
+                    result.files_analysed += 1
+                    if not config.no_cache:
+                        self._cache_backend.put(file, findings)
+                    continue
+
+                findings = self._analysis_engine.analyse(source_file)
+                result.files_analysed += 1
+                logger.debug("analysed: %s", file.file_path)
+
+            # The fix stage owns all autofix policy (eligibility, the
+            # fix loop, writes vs diffs, what to report and cache per
+            # mode); in report mode it hands everything straight back.
+            outcome = self._fix_engine.process(file, findings)
+            result.findings.extend(outcome.findings)
+            if outcome.fixed_by_rule:
+                result.fixed_by_file[file.file_path] = outcome.fixed_by_rule
+            if outcome.diff is not None:
+                result.diffs.append((file.file_path, outcome.diff))
+            # A cache hit stays valid unless the fix stage rewrote the
+            # file, in which case the entry is re-keyed to the fixed
+            # content's identity.
+            if not config.no_cache and (cached is None or outcome.changed):
+                self._cache_backend.put(outcome.metadata, outcome.findings)
+
+        if not config.no_cache:
+            self._cache_backend.write_to_cache()
+
+        result.elapsed = time.perf_counter() - start
+        self._reporter.write_results(result, target)
+        return result

argusf/parser/__init__.py

@@ -0,0 +1 @@
+"""Parsing Fortran source into the intermediate representation."""

argusf/parser/backend.py

@@ -0,0 +1,24 @@
+"""The parsing-engine protocol and its error type."""
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.ir.models import SourceFile, SourceFileMetadata
+
+
+class ParsingEngine(Protocol):
+    """Parses a source file into a `SourceFile` IR tree."""
+
+    def parse(self, file: SourceFileMetadata) -> SourceFile:
+        """Read the file from disk and parse it."""
+        ...
+
+    def parse_source(self, path: Path, source: bytes) -> SourceFile:
+        """Parse source already held in memory (e.g. the fix loop)."""
+        ...
+
+
+class ParseError(Exception):
+    """Raised when a file cannot be read or parsed into IR."""