argusf 0.1.0.dev0__py3-none-any.whl

argusf/config/file_reader/reader.py

@@ -0,0 +1,58 @@
+"""Config-file readers, dispatched by file format."""
+
+import tomllib
+from typing import TYPE_CHECKING, Any, Protocol
+
+from argusf.config.errors import ConfigError
+from argusf.registry import Registry
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class ConfigFileReader(Protocol):
+    """Reads a config file into a raw settings dict."""
+
+    def read(self, file_path: Path) -> dict[str, Any]:
+        """Read and parse `file_path` into a raw settings dict.
+
+        Args:
+            file_path: Path of the config file to read.
+
+        Returns:
+            The parsed top-level table.
+
+        Raises:
+            ConfigError: If the file cannot be read or parsed.
+        """
+
+
+ConfigFileReaderRegistry: Registry[str, type[ConfigFileReader]] = Registry()
+
+
+@ConfigFileReaderRegistry.register("toml")
+class TomlConfigFileReader(ConfigFileReader):
+    """Reads TOML config files via tomllib."""
+
+    def read(self, file_path: Path) -> dict[str, Any]:
+        """Read and parse a TOML config file.
+
+        Args:
+            file_path: Path of the `.toml` file to read.
+
+        Returns:
+            The parsed top-level table.
+
+        Raises:
+            ConfigError: On invalid TOML, non-UTF-8 bytes, or an
+                unreadable file.
+        """
+        try:
+            with open(file_path, "rb") as f:
+                return tomllib.load(f)
+        except tomllib.TOMLDecodeError as error:
+            raise ConfigError(f"invalid {file_path}: {error}") from error
+        except UnicodeDecodeError as error:
+            raise ConfigError(f"invalid {file_path}: not valid UTF-8 ({error})") from error
+        except OSError as error:
+            raise ConfigError(f"cannot read {file_path}: {error}") from error

argusf/config/models.py

@@ -0,0 +1,110 @@
+"""Config data models: CLI/file partials and resolved configs."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from argusf.constants import (
+    DEFAULT_EXCLUDES,
+    DEFAULT_FIXABLE,
+    DEFAULT_INCLUDE,
+    DEFAULT_LARGE_FILE_THRESHOLD,
+    DEFAULT_SELECT,
+    DEFAULT_TASK_TAGS,
+)
+
+
+@dataclass
+class PartialLintConfig:
+    """Optional [lint] settings from one source (None = unset)."""
+
+    extend_fixable: list[str] | None = None
+    extend_select: list[str] | None = None
+    fixable: list[str] | None = None
+    ignore: list[str] | None = None
+    per_file_ignores: dict[str, list[str]] | None = None
+    preview: bool | None = None
+    select: list[str] | None = None
+    task_tags: list[str] | None = None
+    unfixable: list[str] | None = None
+
+
+@dataclass
+class PartialConfig:
+    """Optional top-level settings from one source (None = unset)."""
+
+    cache_dir: Path | None = None
+    exclude: list[str] | None = None
+    extend: Path | None = None
+    extend_exclude: list[str] | None = None
+    extend_include: list[str] | None = None
+    fix: bool | None = None
+    fix_only: bool | None = None
+    include: list[str] | None = None
+    large_file_threshold: int | None = None
+    no_cache: bool | None = None
+    on_large_file: str | None = None
+    output_format: str | None = None
+    required_version: str | None = None
+    respect_gitignore: bool | None = None
+    show_fixes: bool | None = None
+    unsafe_fixes: bool | None = None
+    lint: PartialLintConfig = field(default_factory=PartialLintConfig)
+
+
+@dataclass
+class CliArgs:
+    """Parsed CLI arguments plus inline config option overrides."""
+
+    config: Path | None = None
+    isolated: bool = False
+    verbose: bool = False
+    silent: bool = False
+    options: PartialConfig = field(default_factory=PartialConfig)
+
+
+@dataclass
+class LintConfig:
+    """Resolved lint settings (rule selection, fixes, suppressions)."""
+
+    extend_fixable: list[str] = field(default_factory=list)
+    extend_select: list[str] = field(default_factory=list)
+    # fixable/unfixable/extend_fixable affect the fix payload cached
+    # with each finding, so living here (unlike the runtime
+    # fix/unsafe_fixes flags) also enrols them in the cache fingerprint.
+    fixable: list[str] = field(default_factory=lambda: list(DEFAULT_FIXABLE))
+    ignore: list[str] = field(default_factory=list)
+    per_file_ignores: dict[str, list[str]] = field(default_factory=dict)
+    preview: bool = False
+    select: list[str] = field(default_factory=lambda: list(DEFAULT_SELECT))
+    task_tags: list[str] = field(default_factory=lambda: list(DEFAULT_TASK_TAGS))
+    unfixable: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ArgusConfig:
+    """The fully resolved configuration for a run."""
+
+    cache_dir: Path = field(default_factory=lambda: Path(".argusf_cache"))
+    exclude: list[str] = field(default_factory=lambda: sorted(DEFAULT_EXCLUDES))
+    extend_exclude: list[str] = field(default_factory=list)
+    extend_include: list[str] = field(default_factory=list)
+    extend: Path | None = None
+    # Runtime behaviour flags: they change what is done with findings,
+    # not the findings themselves, so they stay out of the [lint]
+    # fingerprint.
+    fix: bool = False
+    fix_only: bool = False
+    include: list[str] = field(default_factory=lambda: list(DEFAULT_INCLUDE))
+    # Bytes; the TOML value is a unit-suffixed string ("10MB"),
+    # converted at load time. Inert unless on_large_file is set.
+    large_file_threshold: int = DEFAULT_LARGE_FILE_THRESHOLD
+    no_cache: bool = False
+    # One of "warn", "skip", or None (off). File-only, like
+    # large_file_threshold.
+    on_large_file: str | None = None
+    output_format: str = "standard"
+    required_version: str | None = None
+    respect_gitignore: bool = True
+    show_fixes: bool = False
+    unsafe_fixes: bool = False
+    lint: LintConfig = field(default_factory=LintConfig)

argusf/config/validation.py

@@ -0,0 +1,113 @@
+"""Schema validation of raw config-file content."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from argusf.config.errors import ConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+LINT_SECTION = "lint"
+
+
+@dataclass(frozen=True)
+class _ValueType:
+    check: Callable[[object], bool]
+    description: str
+
+
+_STRING = _ValueType(lambda value: isinstance(value, str), "a string")
+_BOOL = _ValueType(lambda value: isinstance(value, bool), "a boolean")
+_STRING_ARRAY = _ValueType(
+    lambda value: isinstance(value, list) and all(isinstance(item, str) for item in value),
+    "an array of strings",
+)
+_PATTERN_TABLE = _ValueType(
+    lambda value: isinstance(value, dict) and all(_STRING_ARRAY.check(selectors) for selectors in value.values()),
+    "a table of pattern = selectors entries",
+)
+
+# Keys mirror PartialConfig/PartialLintConfig fields; TOML-side types,
+# so Path-valued fields are strings here (converted after validation). A
+# test asserts the schemas stay in sync with the dataclasses.
+_TOP_LEVEL_SCHEMA: dict[str, _ValueType] = {
+    "cache_dir": _STRING,
+    "exclude": _STRING_ARRAY,
+    "extend": _STRING,
+    "extend_exclude": _STRING_ARRAY,
+    "extend_include": _STRING_ARRAY,
+    "fix": _BOOL,
+    "fix_only": _BOOL,
+    "include": _STRING_ARRAY,
+    "large_file_threshold": _STRING,
+    "no_cache": _BOOL,
+    "on_large_file": _STRING,
+    "output_format": _STRING,
+    "required_version": _STRING,
+    "respect_gitignore": _BOOL,
+    "show_fixes": _BOOL,
+    "unsafe_fixes": _BOOL,
+}
+_LINT_SCHEMA: dict[str, _ValueType] = {
+    "extend_fixable": _STRING_ARRAY,
+    "extend_select": _STRING_ARRAY,
+    "fixable": _STRING_ARRAY,
+    "ignore": _STRING_ARRAY,
+    "per_file_ignores": _PATTERN_TABLE,
+    "preview": _BOOL,
+    "select": _STRING_ARRAY,
+    "task_tags": _STRING_ARRAY,
+    "unfixable": _STRING_ARRAY,
+}
+
+
+class ConfigSchemaValidator:
+    """Validates raw config-file content before dataclass conversion.
+
+    Rejects unknown keys (so typos fail loudly instead of silently not
+    applying) and wrong-typed values (so shape errors surface as one
+    clean ConfigError at load time rather than a traceback wherever the
+    value first gets used).
+    """
+
+    def validate(self, raw: dict[str, Any], config_path: Path) -> None:
+        """Validate top-level and [lint] keys and value types.
+
+        Args:
+            raw: Parsed config-file content.
+            config_path: Path of the file, used in error messages.
+
+        Raises:
+            ConfigError: On an unknown key or a wrong-typed value.
+        """
+        for key, value in raw.items():
+            if key == LINT_SECTION:
+                self._validate_lint(value, config_path)
+                continue
+            expected = _TOP_LEVEL_SCHEMA.get(key)
+            if expected is None:
+                raise ConfigError(f"unknown key {key!r} in {config_path}")
+            self._check_value(key, value, expected, config_path)
+
+    def _validate_lint(self, section: Any, config_path: Path) -> None:
+        if not isinstance(section, dict):
+            raise ConfigError(f"'{LINT_SECTION}' in {config_path} must be a table")
+        for key, value in section.items():
+            expected = _LINT_SCHEMA.get(key)
+            if expected is None:
+                raise ConfigError(f"unknown key {key!r} in [{LINT_SECTION}] section of {config_path}")
+            self._check_value(f"{LINT_SECTION}.{key}", value, expected, config_path)
+
+    def _check_value(self, dotted_key: str, value: object, expected: _ValueType, config_path: Path) -> None:
+        if expected.check(value):
+            return
+        # TOML array-of-tables ([[lint.per_file_ignores]]) parses to a
+        # list of dicts; it is a documented-syntax trap, so name it
+        # explicitly rather than emitting the generic type message.
+        if expected is _PATTERN_TABLE and isinstance(value, list):
+            raise ConfigError(f"'{dotted_key}' in {config_path} must be a table, not an array of tables")
+        raise ConfigError(
+            f"invalid value for {dotted_key!r} in {config_path}: expected {expected.description}, got {value!r}"
+        )

argusf/constants.py

@@ -0,0 +1,66 @@
+"""Project-wide constants and defaults."""
+
+# Extensions whose contents a Fortran 90 compiler accepts: free-form
+# .f90 plus the fixed-form FORTRAN 77 family, which F90 includes as a
+# strict superset. .fpp is deliberately excluded: it denotes source that
+# requires preprocessing, which argusf does not perform.
+FORTRAN_EXTENSIONS: frozenset[str] = frozenset({".f", ".f77", ".f90", ".for", ".ftn"})
+
+DEFAULT_INCLUDE: tuple[str, ...] = tuple(
+    sorted({f"*{ext}" for ext in FORTRAN_EXTENSIONS} | {f"*{ext.upper()}" for ext in FORTRAN_EXTENSIONS})
+)
+
+# Binary units, insertion-ordered smallest to largest so consumers can
+# scan for the best fit in either direction.
+FILE_SIZE_UNITS: dict[str, int] = {"KB": 1024, "MB": 1024**2, "GB": 1024**3}
+
+# Actions for the `on_large_file` guardrail; unset means the guardrail
+# is off. File-only options — no CLI flags.
+ON_LARGE_FILE_WARN = "warn"
+ON_LARGE_FILE_SKIP = "skip"
+ON_LARGE_FILE_ACTIONS: tuple[str, ...] = (ON_LARGE_FILE_WARN, ON_LARGE_FILE_SKIP)
+DEFAULT_LARGE_FILE_THRESHOLD: int = FILE_SIZE_UNITS["MB"]
+
+DEFAULT_SELECT: tuple[str, ...] = ("RGUS",)
+
+DEFAULT_FIXABLE: tuple[str, ...] = ("ALL",)
+
+MAX_FIX_ITERATIONS: int = 100
+
+# Default lint.task_tags: the labels the todo-comment rule (RGUS008)
+# scans for.
+DEFAULT_TASK_TAGS: tuple[str, ...] = ("TODO", "FIXME", "XXX")
+
+# Discovery-level fnmatch patterns skipped when no `exclude` is
+# configured. A user-provided `exclude` replaces this set entirely while
+# `extend_exclude` adds patterns on top instead. To lint inside one of
+# these (e.g. a directory literally named `build`), target it directly:
+# `argusf check build/` bypasses the default skips at the top level.
+DEFAULT_EXCLUDES: frozenset[str] = frozenset(
+    {
+        # Version control metadata
+        ".git",
+        ".hg",
+        ".svn",
+        # argusf's own cache (default location)
+        ".argusf_cache",
+        # Python dev artifacts commonly present in mixed projects
+        ".venv",
+        "venv",
+        "__pycache__",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        # direnv
+        ".direnv",
+        # Common build output directories
+        "build",
+        "_build",
+        "dist",
+        "bin",
+        "obj",
+        # Editor/IDE metadata
+        ".vscode",
+        ".idea",
+    }
+)

argusf/diagnostics.py

@@ -0,0 +1,45 @@
+"""Developer-facing diagnostics channels, separate from the report."""
+
+from typing import IO, Protocol
+
+import click
+
+
+class Diagnostics(Protocol):
+    """Surfaces developer-facing messages, separate from the report.
+
+    Carries commentary a developer running argusf wants to see
+    (skipped files, parse failures) on stderr, so it never
+    contaminates the parseable findings report on stdout.
+    """
+
+    def emit(self, message: str) -> None:
+        """Emit a diagnostic message."""
+        ...
+
+
+class ClickEchoDiagnostics(Diagnostics):
+    """Writes diagnostics to stderr via click.echo."""
+
+    def __init__(self, stream: IO[str] | None = None) -> None:
+        """Bind the channel to an output stream.
+
+        Args:
+            stream: Destination stream; None writes to stderr.
+        """
+        self._stream = stream
+
+    def emit(self, message: str) -> None:
+        """Write the message to stderr."""
+        click.echo(message, file=self._stream, err=True)
+
+
+class NullDiagnostics(Diagnostics):
+    """Discards diagnostics; used when verbose output is off.
+
+    Lets consumers stay decoupled from the on/off decision — they
+    always emit, and this simply swallows the message.
+    """
+
+    def emit(self, message: str) -> None:
+        """Discard the message."""

argusf/discovery/__init__.py

@@ -0,0 +1,3 @@
+"""Discovery and filtering of source files to analyse."""
+
+from .backend import FileCollector, FileTreeWalker

argusf/discovery/backend.py

@@ -0,0 +1,250 @@
+"""Walking the directory tree to discover Fortran source files."""
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+import pathspec
+
+from argusf.constants import FILE_SIZE_UNITS, ON_LARGE_FILE_SKIP
+from argusf.discovery.gitignore import NullGitignoreMatcher, PathspecGitignoreMatcher
+from argusf.ir.models import SourceFileMetadata
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from argusf.config.models import ArgusConfig
+    from argusf.diagnostics import Diagnostics
+    from argusf.hashing.hash import Hasher
+
+
+@runtime_checkable
+class FileCollector(Protocol):
+    """Streams discovered source files for the orchestrator.
+
+    `collect` yields hashed metadata for the analysis pipeline;
+    `discover_paths` yields bare paths for callers (such as
+    --show-files) that only need the file list.
+    """
+
+    def collect(self, root: Path) -> Iterator[SourceFileMetadata]:
+        """Yield identity metadata for each discovered file.
+
+        Args:
+            root: File or directory to discover under.
+
+        Yields:
+            One `SourceFileMetadata` per file, in the order walked.
+        """
+
+    def discover_paths(self, root: Path) -> Iterator[Path]:
+        """Yield the path of each discovered file without reading it.
+
+        Args:
+            root: File or directory to discover under.
+
+        Yields:
+            One path per discovered file, in the order walked.
+        """
+
+
+def _human_size(size: int) -> str:
+    for unit, scale in reversed(FILE_SIZE_UNITS.items()):
+        if size >= scale:
+            return f"{size / scale:.1f}{unit}"
+    return f"{size}B"
+
+
+def _pattern_spec(base: list[str], extend: list[str]) -> pathspec.GitIgnoreSpec:
+    """Build the shared include/exclude gitignore-style matcher.
+
+    Built from the base + extend pattern lists and matched against each
+    path relative to the walk root (the same matcher the .gitignore
+    support uses). A slashless pattern (*.f90, build) matches a basename
+    at any depth; a pattern containing a slash (src/*.f90, tests/**) is
+    anchored to the root and supports **. An empty pattern list matches
+    nothing.
+    """
+    return pathspec.GitIgnoreSpec.from_lines([*base, *extend])
+
+
+def _relative(path: Path, root: Path) -> str:
+    """Return `path` relative to `root`, POSIX-normalised.
+
+    os.path.relpath is lexical and never yields a leading "./";
+    children of the walk are always below root, so no "../" creeps in.
+    as_posix() normalises separators so the patterns match on every
+    platform.
+    """
+    return Path(os.path.relpath(path, root)).as_posix()
+
+
+class FileTreeWalker(FileCollector):
+    """Discovers Fortran source files by walking the directory tree.
+
+    `diagnostics` is the --verbose-gated developer channel; `warnings`
+    carries the on_large_file notices and is always on — an explicitly
+    configured guardrail should not need --verbose to be visible, and a
+    silently skipped file would hide results.
+    """
+
+    def __init__(
+        self,
+        hasher: Hasher,
+        config: ArgusConfig,
+        diagnostics: Diagnostics,
+        warnings: Diagnostics,
+        config_path: Path | None = None,
+    ) -> None:
+        """Build a walker from its collaborators and config.
+
+        Args:
+            hasher: Hashes file bytes for content identity.
+            config: Resolved config supplying include/exclude, the
+                gitignore toggle, and the large-file guardrail.
+            diagnostics: --verbose-gated channel for skipped or
+                unreadable files.
+            warnings: Always-on channel for on_large_file notices.
+            config_path: Path of the config file whose patterns
+                these are; its directory anchors include/exclude
+                matching. None when no config file applies.
+        """
+        self._hasher = hasher
+        self._diagnostics = diagnostics
+        self._warnings = warnings
+        self._exclude_spec = _pattern_spec(config.exclude, config.extend_exclude)
+        self._include_spec = _pattern_spec(config.include, config.extend_include)
+        # The config file whose patterns these are; its directory is the
+        # anchor for include/exclude matching (see _anchor). None when
+        # no config file applies (isolated, or none found).
+        self._config_path = config_path
+        self._respect_gitignore = config.respect_gitignore
+        self._on_large_file = config.on_large_file
+        self._large_file_threshold = config.large_file_threshold
+
+    def collect(self, root: Path) -> Iterator[SourceFileMetadata]:
+        """Discover files under `root` and hash each one.
+
+        Metadata is streamed one file at a time so source bytes never
+        accumulate across the project — memory stays O(largest file in
+        flight). Each file's bytes are read once to compute its content
+        hash, then discarded; downstream consumers (parser, fix stage)
+        re-read the file when they need the contents. Unreadable files
+        are skipped with a diagnostic.
+
+        Args:
+            root: File or directory to discover under.
+
+        Yields:
+            Lean identity metadata (path, size, mtime, hash) per
+            readable file.
+        """
+        for path in self.discover_paths(root):
+            try:
+                stat = path.stat()
+                source = path.read_bytes()
+            except OSError:
+                self._diagnostics.emit(f"could not read {path}, skipping")
+                continue
+            # The bytes are read for hashing only; downstream consumers
+            # that need them (parser, fix stage) read the file
+            # themselves.
+            yield SourceFileMetadata(
+                file_path=path,
+                size=stat.st_size,
+                mtime=stat.st_mtime,
+                content_hash=self._hasher.hash_bytes(source),
+            )
+
+    def discover_paths(self, root: Path) -> Iterator[Path]:
+        """Yield discovered paths without reading file contents.
+
+        A single-file `root` is yielded as-is, bypassing
+        include/exclude, gitignore, and the large-file guardrail. A
+        directory is walked with excluded and gitignored subtrees
+        pruned from descent; each surviving file is yielded when it
+        matches the include spec and clears the size guardrail.
+
+        Args:
+            root: File or directory to discover under.
+
+        Yields:
+            One path per discovered file.
+        """
+        if root.is_file():
+            # An explicitly named file is analysed as-is —
+            # include/exclude and the extension opinion are all
+            # bypassed, since the user asked for this one specifically.
+            # Downstream just parses it.
+            yield root
+            return
+
+        anchor = self._anchor(root)
+        gitignore = (
+            PathspecGitignoreMatcher(root, self._diagnostics) if self._respect_gitignore else NullGitignoreMatcher()
+        )
+
+        # os.walk lets us prune in-place: dropping a directory from
+        # `dirnames` stops descent into it entirely, rather than walking
+        # and then filtering. Avoids scanning vendored trees (.git,
+        # node_modules, .venv) that contain no Fortran sources. Pruning
+        # gitignored directories also gives git's semantics for free: a
+        # negation deeper in an ignored directory cannot re-include it.
+        for current_dir, dirnames, filenames in os.walk(root):
+            current_path = Path(current_dir)
+            # Absolute so the matcher can relate walked directories to
+            # .gitignore locations even when the walk root is relative.
+            abs_dir = current_path.absolute()
+            dirnames[:] = sorted(
+                d
+                for d in dirnames
+                if not self._is_excluded(current_path / d, anchor) and not gitignore.is_ignored(abs_dir, d, is_dir=True)
+            )
+            for filename in sorted(filenames):
+                file_path = current_path / filename
+                if self._is_excluded(file_path, anchor) or gitignore.is_ignored(abs_dir, filename, is_dir=False):
+                    continue
+                if self._is_included(file_path, anchor) and not self._skip_for_size(file_path):
+                    yield file_path
+
+    def _skip_for_size(self, path: Path) -> bool:
+        """Whether the large-file guardrail skips `path`.
+
+        Checked during discovery (not collect) so `skip` keeps the
+        file out of --show-files too, and skipped files are never
+        read — the point of the guardrail is dodging the parse of
+        pathological files. Like exclude and gitignore, explicitly
+        named single-file targets bypass the check.
+        """
+        if self._on_large_file is None:
+            return False
+        try:
+            size = path.stat().st_size
+        except OSError:
+            return False  # collect() surfaces the unreadable file
+        if size <= self._large_file_threshold:
+            return False
+        if self._on_large_file == ON_LARGE_FILE_SKIP:
+            self._warnings.emit(f"skipping large file ({_human_size(size)}): {path}")
+            return True
+        self._warnings.emit(f"large file ({_human_size(size)}): {path}")
+        return False
+
+    def _anchor(self, target: Path) -> Path:
+        base = (self._config_path.parent if self._config_path is not None else Path.cwd()).absolute()
+        target = target.absolute()
+        return base if target.is_relative_to(base) else target
+
+    def _is_excluded(self, path: Path, anchor: Path) -> bool:
+        return self._exclude_spec.match_file(_relative(path, anchor))
+
+    def _is_included(self, path: Path, anchor: Path) -> bool:
+        """Whether `path` matches the include spec (the file gate).
+
+        The sole file-level gate: a path is discovered only if it
+        matches the resolved include spec (Fortran globs by default).
+        An empty include therefore matches nothing — there is no
+        implicit extension fallback, so downstream can parse whatever
+        discovery yields. Single-file targets bypass this, like exclude.
+        """
+        return self._include_spec.match_file(_relative(path, anchor))