Metadata-Version: 2.4
Name: argusf
Version: 0.1.0.dev0
Summary: A ruff-inspired linter for Fortran 90
Keywords: fortran,linter,static-analysis,static-analyzer,code-quality,fortran90,ruff
Author: Matthew McAteer
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Fortran
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Dist: click>=8.3.3
Requires-Dist: msgpack>=1.2.0
Requires-Dist: packaging>=26.2
Requires-Dist: pathspec>=1.1.1
Requires-Dist: tree-sitter==0.25.2
Requires-Dist: tree-sitter-fortran>=0.6.0
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/mmcateer13/argusf
Project-URL: Repository, https://github.com/mmcateer13/argusf
Project-URL: Issues, https://github.com/mmcateer13/argusf/issues
Description-Content-Type: text/markdown

# argusf

<!-- Badges -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python Version](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/)
<!-- [![CI](https://github.com/mmcateer13/argusf/actions/workflows/YOUR_WORKFLOW.yml/badge.svg)](https://github.com/mmcateer13/argusf/actions) -->

A [ruff](https://github.com/astral-sh/ruff)-inspired linter for Fortran 90.

[Issues](https://github.com/mmcateer13/argusf/issues) | [Contributing](CONTRIBUTING.md) | [Security](SECURITY.md)

## Table of Contents

1. [What is argusf?](#what-is-argusf)
2. [Current State](#current-state)
3. [Getting Started](#getting-started)
4. [Available Rules](#available-rules)
5. [Contributing & Support](#contributing--support)
6. [Acknowledgements](#acknowledgements)
7. [License](#license)

## What is argusf?

argusf is a linter for Fortran 90 codebases, designed with the philosophy of tools like [ruff](https://github.com/astral-sh/ruff): opinionated, and easy to integrate into existing workflows. It analyses your Fortran 90 source files and reports style and quality issues to help you maintain a consistent, readable codebase.

- 🔧 **Zero configuration required** — sensible defaults out of the box; customise via `argusf.toml` when you need to
- 📁 **Scan a file or a whole directory** — just point it at your code
- 📍 **Precise output** — violations reported with file, line, and column
- 🔄 **JSON output support** — easy to integrate into CI pipelines and tooling
- 🎯 **Fortran 90 focused** — purpose-built for the language

## Current State

argusf is an early-stage project. The core internals are working, but the available ruleset is still extremely limited. If you try argusf and encounter unexpected behaviour, missing rules you would find useful, or other issues, please [open an issue](https://github.com/mmcateer13/argusf/issues) — early feedback is especially valuable at this stage.

## Getting Started

### Installation

> [!NOTE]
> If you are planning to contribute to argusf, please see the [contributing guide](CONTRIBUTING.md) and [developer setup instructions](docs/dev_setup.md) instead.

argusf runs on macOS, Linux, and Windows. (Note that the [developer setup instructions](docs/dev_setup.md) currently target macOS and Linux only — this applies to setting up a development environment, not to running the tool.)

Installing argusf requires [uv](https://github.com/astral-sh/uv); if you do not already have it, follow the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).

argusf is not yet available on PyPI. To install it, clone the repository and install it from the local checkout with `uv`, which builds it from source (no PyPI release required) and puts the `argusf` command on your `PATH`:

```bash
git clone https://github.com/mmcateer13/argusf.git
cd argusf
uv tool install --editable .
```

The `--editable` flag means a later `git pull` is picked up without reinstalling. To update after pulling — or if you installed without `--editable` — run `uv tool install --editable . --reinstall`.

### Usage

```bash
argusf check                                         # Analyse the current directory
argusf check path/to/file.f90                        # Analyse a single file
argusf check path/to/your/code/                      # Analyse an entire directory
argusf check --output-format json path/to/your/code/ # Output findings as JSON
argusf check --fix path/to/your/code/                # Apply safe fixes automatically
```

### Configuration

argusf works out of the box with no configuration. To customise behaviour, add an `argusf.toml` file to the root of your project.

The snippet below is equivalent to argusf's out-of-the-box defaults — a handy central reference for what the tool does before you change anything. You only need to include the keys you want to override. It is a hand-maintained snapshot and may lag the code between releases; `argusf --help` and `argusf check --help` are the authoritative source for current defaults.

```toml
# Top-level options
include = ["*.F", "*.F77", "*.F90", "*.FOR", "*.FTN", "*.f", "*.f77", "*.f90", "*.for", "*.ftn"]
exclude = [
    ".argusf_cache", ".direnv", ".git", ".hg", ".idea", ".mypy_cache",
    ".pytest_cache", ".ruff_cache", ".svn", ".venv", ".vscode",
    "__pycache__", "_build", "bin", "build", "dist", "obj", "venv",
]
extend_include = []
extend_exclude = []
respect_gitignore = true
cache_dir = ".argusf_cache"
no_cache = false
output_format = "standard"   # "standard", "concise", or "json"
# on_large_file is unset by default (guardrail off); set "warn" or "skip" to enable.
large_file_threshold = "1MB"
fix = false
fix_only = false
unsafe_fixes = false
show_fixes = false

[lint]
select = ["RGUS"]
extend_select = []
ignore = []
preview = false
fixable = ["ALL"]
unfixable = []
extend_fixable = []
task_tags = ["TODO", "FIXME", "XXX"]
# per_file_ignores is empty by default, e.g.:
# [lint.per_file_ignores]
# "tests/**" = ["RGUS001"]
```

For the full set of options and flags, run `argusf --help` and `argusf check --help` (and `--help` on any subcommand) — these are the authoritative reference for available arguments and options.

## Available Rules

Rule information lives in the CLI itself — use the `argusf rule` command to read a rule's documentation, including its rationale, an example, and any available fix:

```bash
argusf rule --all       # documentation for every rule
argusf rule RGUS001     # documentation for a specific rule
```

Dedicated, per-rule documentation pages are planned for a later release. In the meantime, `argusf rule` is the authoritative source, and you can always read the current ruleset in the [source](https://github.com/mmcateer13/argusf/tree/development/src/argusf/analysis/rules/rulesets).

## Contributing & Support

Contributions are welcome. For bug reports, questions, or feature requests, please [open an issue](https://github.com/mmcateer13/argusf/issues).

If you would like to contribute code, see [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.

To report a security vulnerability, please follow the process in [SECURITY.md](SECURITY.md) rather than opening a public issue.

## Acknowledgements

This project is a faithful iteration on the dissertation project that I completed in my final year of study at [Queen's University Belfast](https://www.qub.ac.uk/), under the supervision of [Prof. Austen Rainer](https://pure.qub.ac.uk/en/persons/austen-rainer/) and [Dr. David Cutting](https://pure.qub.ac.uk/en/persons/david-cutting/). Their support throughout the project's initial development is part of the reason I felt so eager to continue this project today.

A shoutout to the [Astral](https://astral.sh/) team who designed tools such as [ruff](https://github.com/astral-sh/ruff), [uv](https://github.com/astral-sh/uv), and [ty](https://github.com/astral-sh/ty). As an engineer whose (fairly short) career experience is almost entirely Python, the improvements their tooling has made in developer experience across the Python ecosystem has been nothing short of extraordinary. This tool takes heavy inspiration from the `ruff` linter, in an attempt to take even a fraction of this transformative DevEx improvement into the Fortran community!

## License

argusf is licensed under the [MIT License](LICENSE).
