argusf 0.1.0.dev0

A ruff-inspired linter for Fortran 90

argusf

A ruff-inspired linter for Fortran 90.

Issues | Contributing | Security

Table of Contents

1. What is argusf?
2. Current State
3. Getting Started
4. Available Rules
5. Contributing & Support
6. Acknowledgements
7. License

What is argusf?

argusf is a linter for Fortran 90 codebases, designed with the philosophy of tools like 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 — 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 and developer setup instructions instead.

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

Installing argusf requires uv; if you do not already have it, follow the uv installation guide.

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:

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

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.

# 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:

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.

Contributing & Support

Contributions are welcome. For bug reports, questions, or feature requests, please open an issue.

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

To report a security vulnerability, please follow the process in 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, under the supervision of Prof. Austen Rainer and Dr. 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 team who designed tools such as ruff, uv, and 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.