argusf 0.1.0.dev0__py3-none-any.whl

argusf/cli.py

@@ -0,0 +1,428 @@
+"""The argusf command-line interface (Click entry point)."""
+
+import importlib.metadata
+import platform
+import shutil
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+
+from argusf.analysis.engine import AnalysisEngine
+from argusf.analysis.rules import RuleRegistry
+from argusf.analysis.rules.documentation import RuleDocumentationRenderer
+from argusf.analysis.suppression import SuppressionFilter
+from argusf.autofix import FixContext, FixEngine, FixMode, build_fix_context
+from argusf.cache.backend import CacheBackend
+from argusf.config.config_resolver import ConfigResolver
+from argusf.config.errors import ConfigError
+from argusf.config.models import ArgusConfig, CliArgs, PartialConfig, PartialLintConfig
+from argusf.diagnostics import ClickEchoDiagnostics, Diagnostics, NullDiagnostics
+from argusf.discovery.backend import FileTreeWalker
+from argusf.hashing.hash import HashBackend
+from argusf.orchestrator import Orchestrator
+from argusf.parser.treesitter.backend import TreesitterParsingEngine
+from argusf.reporting import DiffReporter, NullReporter, Reporter, ReporterRegistry, StatisticsReporter
+
+if TYPE_CHECKING:
+    from argusf.ir.models import RunResult
+
+FINDINGS_EXIT_CODE = 1
+ERROR_EXIT_CODE = 2
+
+
+def _parse_selectors(values: tuple[str, ...]) -> list[str] | None:
+    if not values:
+        return None
+    return [code.strip() for value in values for code in value.split(",") if code.strip()]
+
+
+def _resolve_config(cli_args: CliArgs) -> ArgusConfig:
+    try:
+        return ConfigResolver().resolve_config(cli_args)
+    except ConfigError as error:
+        click.echo(f"argusf: {error}", err=True)
+        sys.exit(ERROR_EXIT_CODE)
+
+
+def _resolve_reporter(config: ArgusConfig, silent: bool, statistics: bool, fix_context: FixContext) -> Reporter:
+    if silent:
+        return NullReporter()
+
+    # In diff mode the diffs are the report, whatever --output-format
+    # says; --statistics + --diff is rejected upstream.
+    if fix_context.mode is FixMode.DIFF:
+        return DiffReporter(fix_context=fix_context)
+
+    if statistics:
+        return StatisticsReporter(config.output_format, fix_context=fix_context)
+
+    reporter_cls = ReporterRegistry.get(config.output_format)
+    if reporter_cls is None:
+        raise ValueError(
+            f"Got invalid output format {config.output_format!r}. Must be one of {ReporterRegistry.keys()!s}"
+        )
+    # The Reporter protocol deliberately types behaviour, not
+    # construction; every registered reporter accepts this keyword.
+    return reporter_cls(fix_context=fix_context)  # type: ignore[call-arg]
+
+
+def _check_exit_code(result: RunResult, fix_context: FixContext, *, exit_non_zero_on_fix: bool, exit_zero: bool) -> int:
+    if fix_context.mode is FixMode.DIFF:
+        return FINDINGS_EXIT_CODE if result.diffs and not exit_zero else 0
+    if exit_non_zero_on_fix and result.fixed_count:
+        return FINDINGS_EXIT_CODE
+    if fix_context.mode is FixMode.FIX_ONLY:
+        return 0
+    if result.active_findings() and not exit_zero:
+        return FINDINGS_EXIT_CODE
+    return 0
+
+
+def _build_orchestrator(  # noqa: PLR0913
+    config: ArgusConfig,
+    target: Path,
+    diagnostics: Diagnostics,
+    reporter: Reporter,
+    config_path: Path | None,
+    fix_context: FixContext,
+) -> Orchestrator:
+    hasher = HashBackend()
+    parsing_engine = TreesitterParsingEngine(diagnostics)
+    analysis_engine = AnalysisEngine(config, SuppressionFilter(config, target))
+    return Orchestrator(
+        file_collector=FileTreeWalker(hasher, config, diagnostics, ClickEchoDiagnostics(), config_path),
+        parsing_engine=parsing_engine,
+        analysis_engine=analysis_engine,
+        cache_backend=CacheBackend(
+            importlib.metadata.version("argusf"), platform.python_version(), config, diagnostics, hasher
+        ),
+        fix_engine=FixEngine(
+            parsing_engine=parsing_engine,
+            analyser=analysis_engine,
+            hasher=hasher,
+            context=fix_context,
+            diagnostics=diagnostics,
+        ),
+        diagnostics=diagnostics,
+        reporter=reporter,
+    )
+
+
+@click.group()
+@click.version_option(version=importlib.metadata.version("argusf"), prog_name="argusf")
+@click.option(
+    "--config",
+    type=click.Path(file_okay=True, dir_okay=False, path_type=Path),
+    help="Path to a TOML configuration file to use instead of discovering argusf.toml.",
+)
+@click.option(
+    "--isolated",
+    is_flag=True,
+    default=False,
+    help="Ignore all configuration files.",
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    default=False,
+    help="Print diagnostics (skipped files, parse failures) to stderr.",
+)
+@click.option(
+    "--silent",
+    "-s",
+    is_flag=True,
+    default=False,
+    help="Suppress the findings report on stdout; exit codes are unaffected.",
+)
+@click.pass_context
+def cli(ctx: click.Context, config: Path | None, isolated: bool, verbose: bool, silent: bool) -> None:
+    """Argus — A static code analyser for Fortran 90."""
+    ctx.obj = CliArgs(config=config, isolated=isolated, verbose=verbose, silent=silent)
+
+
+@cli.command()
+@click.argument(
+    "target",
+    required=False,
+    type=click.Path(exists=True, file_okay=True, dir_okay=True, resolve_path=True, path_type=Path),
+)
+@click.option(
+    "--preview/--no-preview",
+    default=None,
+    help="Enable rules marked as being in preview.",
+)
+@click.option(
+    "--no-cache",
+    "-n",
+    is_flag=True,
+    default=False,
+    help="Disable cache reads.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(list(ReporterRegistry.keys())),
+    default=None,
+    help="Format for the findings report.",
+)
+@click.option(
+    "--show-files",
+    is_flag=True,
+    default=False,
+    help="List the files that would be analysed, without analysing them.",
+)
+@click.option(
+    "--exclude",
+    multiple=True,
+    metavar="PATTERN",
+    help="Replace the exclude list with these fnmatch patterns. May be repeated; not comma-split.",
+)
+@click.option(
+    "--extend-exclude",
+    multiple=True,
+    metavar="PATTERN",
+    help="Add an fnmatch pattern on top of the resolved exclude list. May be repeated; not comma-split.",
+)
+@click.option(
+    "--include",
+    multiple=True,
+    metavar="PATTERN",
+    help="Restrict discovery to Fortran files whose name matches these fnmatch patterns. "
+    "May be repeated; not comma-split.",
+)
+@click.option(
+    "--extend-include",
+    multiple=True,
+    metavar="PATTERN",
+    help="Add an fnmatch pattern on top of the resolved include list. May be repeated; not comma-split.",
+)
+@click.option(
+    "--respect-gitignore/--no-respect-gitignore",
+    default=None,
+    help="Honour .gitignore files during file discovery.",
+)
+@click.option(
+    "--select",
+    multiple=True,
+    metavar="SELECTORS",
+    help="Enable only these rules. Selectors are rule codes (RGUS001), prefixes (RGUS), or ALL; "
+    "comma-separated and repeatable.",
+)
+@click.option(
+    "--extend-select",
+    multiple=True,
+    metavar="SELECTORS",
+    help="Rules to enable on top of the resolved select without replacing it.",
+)
+@click.option(
+    "--ignore",
+    multiple=True,
+    metavar="SELECTORS",
+    help="Disable these rules. The most specific selector wins; on a tie, ignore beats select.",
+)
+@click.option(
+    "--fixable",
+    multiple=True,
+    metavar="SELECTORS",
+    help="Rules whose fixes may be applied. Same selector syntax as --select; defaults to ALL.",
+)
+@click.option(
+    "--unfixable",
+    multiple=True,
+    metavar="SELECTORS",
+    help="Rules whose fixes are never applied (their findings are still reported).",
+)
+@click.option(
+    "--extend-fixable",
+    multiple=True,
+    metavar="SELECTORS",
+    help="Rules to treat as fixable on top of the resolved fixable list without replacing it.",
+)
+@click.option(
+    "--fix/--no-fix",
+    default=None,
+    help="Apply safe fixes for the resolved fixable rules; add --unsafe-fixes to widen.",
+)
+@click.option(
+    "--unsafe-fixes/--no-unsafe-fixes",
+    default=None,
+    help="Also display and (with --fix) apply fixes that may change program behaviour.",
+)
+@click.option(
+    "--fix-only/--no-fix-only",
+    default=None,
+    help="Apply fixes but do not report or exit non-zero for leftover findings. Implies --fix.",
+)
+@click.option(
+    "--show-fixes/--no-show-fixes",
+    default=None,
+    help="Enumerate the applied fixes after a fixing run.",
+)
+@click.option(
+    "--diff",
+    is_flag=True,
+    default=False,
+    help="Show what --fix would change as a diff, without writing any file. Exits 1 if a diff exists.",
+)
+@click.option(
+    "--exit-non-zero-on-fix",
+    is_flag=True,
+    default=False,
+    help="Exit 1 if any file was modified by fixes, even when no findings remain.",
+)
+@click.option(
+    "--exit-zero",
+    "-e",
+    is_flag=True,
+    default=False,
+    help="Exit 0 even when findings remain (or a --diff would change files). Tool errors still exit 2.",
+)
+@click.option(
+    "--statistics",
+    is_flag=True,
+    default=False,
+    help="Report per-rule finding counts instead of individual findings.",
+)
+@click.pass_obj
+def check(  # noqa: PLR0913
+    cli_args: CliArgs,
+    preview: bool | None,
+    no_cache: bool,
+    output_format: str | None,
+    show_files: bool,
+    exclude: tuple[str, ...],
+    extend_exclude: tuple[str, ...],
+    include: tuple[str, ...],
+    extend_include: tuple[str, ...],
+    respect_gitignore: bool | None,
+    select: tuple[str, ...],
+    extend_select: tuple[str, ...],
+    ignore: tuple[str, ...],
+    fixable: tuple[str, ...],
+    unfixable: tuple[str, ...],
+    extend_fixable: tuple[str, ...],
+    fix: bool | None,
+    unsafe_fixes: bool | None,
+    fix_only: bool | None,
+    show_fixes: bool | None,
+    diff: bool,
+    exit_non_zero_on_fix: bool,
+    exit_zero: bool,
+    statistics: bool,
+    target: Path | None,
+) -> None:
+    """Analyse Fortran source files and report findings.
+
+    TARGET is a file or directory to analyse; defaults to the current
+    directory. Directories are searched recursively for Fortran sources.
+
+    Exits 0 when no active findings are found, 1 when there are active
+    findings, and 2 on a tool error (e.g. invalid options).
+    """
+    target = target or Path.cwd()
+    diagnostics: Diagnostics = ClickEchoDiagnostics() if cli_args.verbose else NullDiagnostics()
+
+    if statistics and diff:
+        click.echo("argusf: --statistics and --diff are mutually exclusive", err=True)
+        sys.exit(ERROR_EXIT_CODE)
+
+    # Contradictory exit-code demands.
+    if exit_zero and exit_non_zero_on_fix:
+        click.echo("argusf: --exit-zero and --exit-non-zero-on-fix are mutually exclusive", err=True)
+        sys.exit(ERROR_EXIT_CODE)
+
+    cli_args.options = PartialConfig(
+        lint=PartialLintConfig(
+            preview=preview,
+            select=_parse_selectors(select),
+            extend_select=_parse_selectors(extend_select),
+            ignore=_parse_selectors(ignore),
+            fixable=_parse_selectors(fixable),
+            unfixable=_parse_selectors(unfixable),
+            extend_fixable=_parse_selectors(extend_fixable),
+        ),
+        exclude=list(exclude) or None,
+        extend_exclude=list(extend_exclude) or None,
+        include=list(include) or None,
+        extend_include=list(extend_include) or None,
+        respect_gitignore=respect_gitignore,
+        no_cache=no_cache or None,
+        output_format=output_format,
+        fix=fix,
+        unsafe_fixes=unsafe_fixes,
+        fix_only=fix_only,
+        show_fixes=show_fixes,
+    )
+    config = _resolve_config(cli_args)
+    config_path = ConfigResolver().config_path(cli_args)
+    fix_context = build_fix_context(config, diff=diff)
+
+    if show_files:
+        walker = FileTreeWalker(HashBackend(), config, diagnostics, ClickEchoDiagnostics(), config_path)
+        for path in walker.discover_paths(target):
+            click.echo(path)
+        return
+
+    try:
+        reporter = _resolve_reporter(config, cli_args.silent, statistics, fix_context)
+        orchestrator = _build_orchestrator(config, target, diagnostics, reporter, config_path, fix_context)
+    except ValueError as error:
+        click.echo(f"argusf: {error}", err=True)
+        sys.exit(ERROR_EXIT_CODE)
+
+    result = orchestrator.run(target=target, config=config)
+    exit_code = _check_exit_code(result, fix_context, exit_non_zero_on_fix=exit_non_zero_on_fix, exit_zero=exit_zero)
+    if exit_code:
+        sys.exit(exit_code)
+
+
+@cli.command()
+@click.pass_obj
+def clean(cli_args: CliArgs) -> None:
+    """Remove the cache directory."""
+    config = _resolve_config(cli_args)
+    cache_dir = Path(config.cache_dir)
+    if cache_dir.exists():
+        click.echo(f"Removing cache at: {click.style(str(cache_dir), bold=True)}")
+        shutil.rmtree(cache_dir)
+
+
+@cli.command()
+@click.argument(
+    "code",
+    required=False,
+)
+@click.option(
+    "--all",
+    "show_all",
+    is_flag=True,
+    default=False,
+    help="Show the documentation for every rule.",
+)
+def rule(code: str | None, show_all: bool) -> None:
+    """Show the documentation for a rule (or all rules with --all).
+
+    CODE is an exact rule code, e.g. RGUS001; prefixes are not accepted.
+    """
+    renderer = RuleDocumentationRenderer()
+    if show_all:
+        if code is not None:
+            click.echo("argusf: Provide either a rule code or --all, not both", err=True)
+            sys.exit(ERROR_EXIT_CODE)
+        click.echo("\n\n".join(renderer.render(rule_cls) for rule_cls in RuleRegistry.values()))
+        return
+    if code is None:
+        click.echo("argusf: Provide a rule code or --all", err=True)
+        sys.exit(ERROR_EXIT_CODE)
+
+    rule_cls = RuleRegistry.get(code)
+    if rule_cls is None:
+        click.echo(f"argusf: Unknown rule code: {code!r}", err=True)
+        sys.exit(ERROR_EXIT_CODE)
+    click.echo(renderer.render(rule_cls))
+
+
+if __name__ == "__main__":
+    cli()

argusf/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration resolution, models, and validation."""

argusf/config/config_resolver.py

@@ -0,0 +1,212 @@
+"""Resolving the final config from CLI args and config files."""
+
+import importlib.metadata
+import re
+from dataclasses import fields, is_dataclass
+from pathlib import Path
+from typing import Any
+
+from packaging.specifiers import InvalidSpecifier, SpecifierSet
+
+from argusf.constants import FILE_SIZE_UNITS, ON_LARGE_FILE_ACTIONS
+from argusf.discovery.repo import find_repo_root
+
+from .errors import ConfigError
+from .file_reader import ConfigFileReaderRegistry
+from .models import ArgusConfig, CliArgs, LintConfig, PartialConfig, PartialLintConfig
+from .validation import LINT_SECTION, ConfigSchemaValidator
+
+
+class ConfigResolver:
+    """Merges CLI arguments with config-file settings into a config."""
+
+    def __init__(self, version: str | None = None) -> None:
+        """Bind the resolver to a running argusf version.
+
+        Args:
+            version: Version used to enforce required_version;
+                defaults to the installed argusf version.
+        """
+        self._version = version or importlib.metadata.version("argusf")
+
+    def resolve_config(self, cli_args: CliArgs) -> ArgusConfig:
+        """Resolve the final config for a run.
+
+        Reads the governing config file (unless isolated), merges it
+        under the CLI arguments (CLI > file > default), and enforces
+        required_version when the file sets it.
+
+        Args:
+            cli_args: Parsed CLI arguments, including inline options.
+
+        Returns:
+            The fully resolved configuration.
+
+        Raises:
+            ConfigError: On an unreadable/invalid file or an
+                unsatisfied required_version.
+        """
+        config_path = self.config_path(cli_args)
+        file_options = self._load_file(config_path) if config_path is not None else PartialConfig()
+
+        config = self._merge(cli_args.options, file_options)
+        # required_version has no CLI flag, so it can only be set when a
+        # config file was read; config_path is never None here.
+        if config.required_version is not None and config_path is not None:
+            self._enforce_required_version(config.required_version, config_path)
+        return config
+
+    def config_path(self, cli_args: CliArgs) -> Path | None:
+        """Return the config file that governs this run, or None.
+
+        Exposed so discovery can anchor include/exclude patterns to
+        the config file's directory.
+
+        Args:
+            cli_args: Parsed CLI arguments.
+
+        Returns:
+            The `--config` path, else the discovered argusf.toml,
+            else None (isolated mode, or none found).
+        """
+        if cli_args.isolated:
+            return None
+        return cli_args.config or self._discover_config_file()
+
+    def _load_file(self, config_path: Path) -> PartialConfig:
+        file_format = config_path.suffix.replace(".", "")
+        reader = ConfigFileReaderRegistry.get(file_format)
+        if reader is None:
+            raise ConfigError(f"unsupported config file format: {file_format!r}")
+
+        raw = reader().read(config_path)
+        ConfigSchemaValidator().validate(raw, config_path)
+        raw_lint = raw.pop(LINT_SECTION, {})
+
+        if "cache_dir" in raw:
+            raw["cache_dir"] = Path(raw["cache_dir"])
+        if "extend" in raw:
+            raw["extend"] = Path(raw["extend"])
+        if "on_large_file" in raw and raw["on_large_file"] not in ON_LARGE_FILE_ACTIONS:
+            raise ConfigError(
+                f"invalid value for 'on_large_file' in {config_path}:"
+                f" expected one of {ON_LARGE_FILE_ACTIONS!s}, got {raw['on_large_file']!r}"
+            )
+        if "large_file_threshold" in raw:
+            raw["large_file_threshold"] = self._parse_file_size(raw["large_file_threshold"], config_path)
+
+        return PartialConfig(**raw, lint=PartialLintConfig(**raw_lint))
+
+    def _parse_file_size(self, value: str, config_path: Path) -> int:
+        """Parse a size string like "500KB" or "10MB" into bytes.
+
+        A number with an optional binary-unit suffix; bare digits are
+        bytes. Converted at the load boundary, like cache_dir to Path,
+        so a malformed value fails here (exit 2) instead of wherever
+        the walker first compares sizes.
+
+        Raises:
+            ConfigError: On a value that is not a valid size.
+        """
+        match = re.fullmatch(r"(\d+(?:\.\d+)?)\s*([A-Za-z]+)?", value.strip())
+        unit = None if match is None else match.group(2)
+        if match is None or (unit is not None and unit.upper() not in FILE_SIZE_UNITS):
+            raise ConfigError(
+                f"invalid value for 'large_file_threshold' in {config_path}:"
+                f' expected a size like "500KB" or "10MB", got {value!r}'
+            )
+        scale = 1 if unit is None else FILE_SIZE_UNITS[unit.upper()]
+        return int(float(match.group(1)) * scale)
+
+    def _enforce_required_version(self, required_version: str, config_path: Path) -> None:
+        try:
+            specifiers = SpecifierSet(required_version)
+        except InvalidSpecifier:
+            # A bare version ("0.1.0") means an exact match.
+            try:
+                specifiers = SpecifierSet(f"=={required_version}")
+            except InvalidSpecifier as error:
+                raise ConfigError(
+                    f"invalid required_version {required_version!r} in {config_path}: not a valid version specifier"
+                ) from error
+        if not specifiers.contains(self._version, prereleases=True):
+            raise ConfigError(
+                f"argusf {self._version} does not satisfy required_version {required_version!r} in {config_path}"
+            )
+
+    def _merge(self, cli: PartialConfig, file: PartialConfig) -> ArgusConfig:
+        lint = LintConfig(**self._resolve_fields(LintConfig, cli.lint, file.lint))
+        return ArgusConfig(**self._resolve_fields(ArgusConfig, cli, file), lint=lint)
+
+    def _resolve_fields(
+        self,
+        resolved_cls: type[ArgusConfig | LintConfig],
+        cli: PartialConfig | PartialLintConfig,
+        file: PartialConfig | PartialLintConfig,
+    ) -> dict[str, Any]:
+        """Resolve each field with CLI > file > default precedence.
+
+        Keyed by field name, so newly added config fields merge without
+        touching this code. Nested dataclass fields (e.g. lint) hold
+        partial sub-configs on the input side and are merged by their
+        own _resolve_fields call, so they are skipped here.
+        """
+        defaults = resolved_cls()
+        resolved: dict[str, Any] = {}
+        for field in fields(resolved_cls):
+            default_value = getattr(defaults, field.name)
+            if is_dataclass(default_value):
+                continue
+
+            cli_value = getattr(cli, field.name)
+            file_value = getattr(file, field.name)
+            if cli_value is not None:
+                resolved[field.name] = cli_value
+            elif file_value is not None:
+                resolved[field.name] = file_value
+            else:
+                resolved[field.name] = default_value
+        return resolved
+
+    def _discover_config_file(self) -> Path | None:
+        """Find the argusf.toml for this run by walking up from cwd.
+
+        Starts at the current working directory and ascends, nearest
+        file winning, stopping at the repo root (nearest ancestor with a
+        `.git` entry) or at cwd outside a repository — so a stray
+        ~/argusf.toml can never apply (same boundary semantics as
+        gitignore discovery).
+
+        This is anchored on **cwd, not the analysis target**: argusf
+        uses a single config for the whole run, found relative to where
+        the tool is invoked, rather than resolving configuration
+        per-target file (walking up from each linted path, which is what
+        lets a monorepo carry per-directory configs).
+
+        Consequence: running from the project root or any subdirectory
+        (including under CI or a pre-commit hook, which cd into the
+        repo) discovers the same file. The single-config model shows
+        only when running from *outside* a project and targeting into it
+        (that project's config is not found, so defaults apply), or for
+        monorepos with per-package configs (only the cwd-relative one
+        applies).
+
+        Revisiting this (per-target / hierarchical resolution) is
+        deliberately deferred: it is a config-layer change rather than a
+        tweak, and the case that most wants it is editor/LSP
+        integration, where tools invoke argusf with absolute paths from
+        an arbitrary cwd. Pattern anchoring does not depend on it —
+        ``_anchor`` (discovery backend) anchors to wherever the config
+        was found — so switching the discovery mechanism later needs no
+        rework there.
+        """
+        # TODO: .ini support
+        start = Path.cwd().absolute()
+        boundary = find_repo_root(start) or start
+        for directory in (start, *start.parents):
+            candidate = directory / "argusf.toml"
+            if candidate.exists():
+                return candidate
+            if directory == boundary:
+                return None
+        return None

argusf/config/errors.py

@@ -0,0 +1,8 @@
+"""The error type raised for bad configuration files."""
+
+
+class ConfigError(ValueError):
+    """A config file is unreadable, malformed, or has invalid values.
+
+    Surfaced by the CLI as a clean error message with exit code 2.
+    """

argusf/config/file_reader/__init__.py

@@ -0,0 +1,3 @@
+from .reader import ConfigFileReaderRegistry
+
+__all__ = ["ConfigFileReaderRegistry"]