argusf 0.1.0.dev0__tar.gz

argusf-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew McAteer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

argusf-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,166 @@
+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).

argusf-0.1.0.dev0/README.md

@@ -0,0 +1,137 @@
+# 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).

argusf-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,142 @@
+[project]
+name = "argusf"
+version = "0.1.0.dev0"
+description = "A ruff-inspired linter for Fortran 90"
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Matthew McAteer" },
+]
+keywords = ["fortran", "linter", "static-analysis", "static-analyzer", "code-quality", "fortran90", "ruff"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Fortran",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "click>=8.3.3",
+    "msgpack>=1.2.0",
+    "packaging>=26.2",
+    "pathspec>=1.1.1",
+    # Pinned due to SEGFAULTs on v0.26 when testing
+    # the package on .F files.
+    "tree-sitter==0.25.2",
+    "tree-sitter-fortran>=0.6.0",
+]
+
+[project.scripts]
+argusf = "argusf.cli:cli"
+
+[project.urls]
+Homepage = "https://github.com/mmcateer13/argusf"
+Repository = "https://github.com/mmcateer13/argusf"
+Issues = "https://github.com/mmcateer13/argusf/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.27,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "argusf"
+module-root = "src"
+
+[tool.ruff]
+line-length = 120
+target-version = "py314"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Type annotations on args/returns — we do our typing-related linting with mypy.
+    "ANN",
+    # Boolean positional/default args — conflicts with click's decorator pattern
+    "FBT001", "FBT002",
+    # TODO must include author and issue link — too strict
+    "TD002", "TD003",
+    # Line contains TODO — flags every TODO as a violation, unhelpful
+    "FIX002",
+    # Exception messages must be extracted into a variable before raising — adds verbosity for little gain
+    "TRY003", "EM102",
+    # Conflicts with ruff auto-formatter
+    "COM812",
+    # Replace 'open()' with 'Path.open()'
+    "PTH123",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["argusf"]
+
+[tool.ruff.lint.pycodestyle]
+max-doc-length = 72
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = [
+    # Unused imports
+    "F401",
+    # Package docstrings — re-export shims don't need them; the few
+    # __init__ files worth documenting are documented anyway.
+    "D",
+]
+"src/argusf/analysis/rules/rulesets/**" = [
+    # Rule docstrings carry long-flowing prose documentation on purpose.
+    "W505",
+    "D",
+]
+"src/argusf/parser/treesitter/walker/handlers.py" = [
+    # Node parsing handlers are fairly self-explanatory without docstrings.
+    "D",
+]
+"tests/**" = [
+    # Use of assert
+    "S101",
+    # Private member access — tests legitimately inspect internals
+    "SLF001",
+    # Magic values in comparisons — expected in test assertions
+    "PLR2004",
+    # Docstring-related rules
+    "D",
+]
+
+[tool.mypy]
+python_version = "3.14"
+mypy_path = ["src"]
+packages = ["argusf"]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = ["tree_sitter.*", "tree_sitter_fortran.*", "msgpack.*"]
+ignore_missing_imports = true
+
+[tool.pytest]
+testpaths = ["tests"]
+
+[tool.uv]
+exclude-newer = "1 week"
+package = true
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0",
+    "pytest>=9.0.3",
+    "ruff>=0.15.12",
+]

argusf-0.1.0.dev0/src/argusf/__init__.py

@@ -0,0 +1,3 @@
+"""Argusf: a static code analyzer for Fortran 90."""
+
+__version__ = "0.1.0"

argusf-0.1.0.dev0/src/argusf/analysis/__init__.py

@@ -0,0 +1,14 @@
+"""Rule-based analysis of parsed source into findings."""
+
+from .engine import AnalysisEngine
+from .rule import Rule, RuleMetadata
+from .rules import RuleRegistry
+from .suppression import SuppressionFilter
+
+__all__ = [
+    "AnalysisEngine",
+    "Rule",
+    "RuleMetadata",
+    "RuleRegistry",
+    "SuppressionFilter",
+]

argusf-0.1.0.dev0/src/argusf/analysis/engine.py

@@ -0,0 +1,100 @@
+"""The analysis engine: runs rules over a parsed source file."""
+
+import logging
+from typing import TYPE_CHECKING
+
+from argusf.analysis.rule import ConfigurableRule, Rule
+from argusf.analysis.rules import RuleRegistry
+from argusf.analysis.rules.selection import RuleSelectionResolver
+from argusf.analysis.syntax_errors import syntax_error_finding
+
+if TYPE_CHECKING:
+    from argusf.analysis.suppression import SuppressionFilter
+    from argusf.config.models import ArgusConfig
+    from argusf.ir.models import Finding, SourceFile
+
+logger = logging.getLogger(__name__)
+
+
+class AnalysisEngine:
+    """Runs the configured rules over a source file."""
+
+    def __init__(self, config: ArgusConfig, suppression_filter: SuppressionFilter) -> None:
+        """Build the engine's rule set from config.
+
+        Constructs every registered rule, configures the ones that
+        read settings, filters by select/ignore and preview, and
+        resolves which rules may attach fixes.
+
+        Args:
+            config: Resolved configuration; its lint section drives
+                rule selection and fixability.
+            suppression_filter: Filter applied to findings after the
+                rules run.
+        """
+        self._config = config.lint
+        self._suppression_filter = suppression_filter
+        rules: list[Rule] = []
+        for rule_cls in RuleRegistry.values():
+            rule = rule_cls()
+            if isinstance(rule, ConfigurableRule):
+                rule.configure(self._config)
+            rules.append(rule)
+        self._rules = self._filter_rules(rules)
+        # A rule's fix survives only if the rule declares itself fixable
+        # (metadata is authoritative) AND the fixable/unfixable
+        # selectors resolve it in.
+        declared_fixable = {rule.metadata.id for rule in rules if rule.metadata.fixable}
+        self._fixable = declared_fixable & RuleSelectionResolver().resolve(
+            [*self._config.fixable, *self._config.extend_fixable], self._config.unfixable
+        )
+
+    def analyse(self, source_file: SourceFile) -> list[Finding]:
+        """Produce all findings for a parsed source file.
+
+        Seeds syntax-error findings from the parser, runs each enabled
+        rule, strips fixes from rules outside the fixable set, and
+        marks suppressed findings.
+
+        Args:
+            source_file: The parsed file to analyse.
+
+        Returns:
+            Findings in document order, some flagged suppressed.
+        """
+        # Syntax errors precede rule findings; they come from the
+        # parser, not a rule, so rule selection never applies to them.
+        findings: list[Finding] = [
+            syntax_error_finding(source_file.file_path, span) for span in source_file.syntax_errors
+        ]
+        for rule in self._rules:
+            rule_findings = rule.check(source_file)
+            if rule_findings:
+                logger.debug(
+                    "%s: %d finding(s) from %s",
+                    source_file.file_path,
+                    len(rule_findings),
+                    rule.metadata.id,
+                )
+                findings.extend(rule_findings)
+
+        # Strip fixes for rules outside the resolved fixable set before
+        # findings are cached or reported, so a finding's payload always
+        # matches what fixable/unfixable said at analysis time — an
+        # unfixable rule's findings carry no fix anywhere, including the
+        # JSON report's `fix: null`.
+        for finding in findings:
+            if finding.fix is not None and finding.rule_id not in self._fixable:
+                finding.fix = None
+
+        self._suppression_filter.apply(source_file, findings)
+        return findings
+
+    def _filter_rules(self, rules: list[Rule]) -> list[Rule]:
+        select = [*self._config.select, *self._config.extend_select]
+        enabled = RuleSelectionResolver().resolve(select, self._config.ignore)
+        return [
+            rule
+            for rule in rules
+            if rule.metadata.id in enabled and (self._config.preview or not rule.metadata.preview)
+        ]

argusf-0.1.0.dev0/src/argusf/analysis/rule.py

@@ -0,0 +1,45 @@
+"""Rule protocols and the metadata attached to each rule."""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from argusf.config.models import LintConfig
+    from argusf.ir.models import Finding, Severity, SourceFile
+
+
+@dataclass(frozen=True)
+class RuleMetadata:
+    """Static metadata describing a rule."""
+
+    id: str
+    name: str
+    message: str
+    description: str
+    default_severity: Severity
+    suggestion: str | None = None
+    preview: bool = False
+    # The fixable-rule contract. A rule that offers fixes declares it
+    # here and must document the classification in a `## Fix safety`
+    # docstring section (a registry test enforces both directions). The
+    # declaration is authoritative: the engine strips fixes from any
+    # rule that does not make it, so an undeclared fix can never reach a
+    # report, the cache, or a file.
+    fixable: bool = False
+
+
+class Rule(Protocol):
+    """A lint rule: metadata plus a check over a source file."""
+
+    metadata: RuleMetadata
+
+    def check(self, source_file: SourceFile) -> list[Finding]:
+        """Return the findings this rule detects in `source_file`."""
+
+
+@runtime_checkable
+class ConfigurableRule(Rule, Protocol):
+    """A rule that reads lint settings via `configure`."""
+
+    def configure(self, config: LintConfig) -> None:
+        """Receive the resolved lint config before analysis."""

argusf-0.1.0.dev0/src/argusf/analysis/rules/__init__.py

@@ -0,0 +1,5 @@
+# Import rulesets to trigger registration of the built-in rules.
+from . import rulesets
+from .registry import RuleRegistry, register
+
+__all__ = ["RuleRegistry", "register", "rulesets"]

argusf-0.1.0.dev0/src/argusf/analysis/rules/documentation.py

@@ -0,0 +1,30 @@
+"""Rendering a rule's long-form documentation for the CLI."""
+
+import inspect
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from argusf.analysis.rule import Rule
+
+
+class RuleDocumentationRenderer:
+    """Renders a rule's docstring for the `argusf rule` command."""
+
+    def render(self, rule_cls: type[Rule]) -> str:
+        """Render a rule's documentation as markdown.
+
+        Uses the rule class's own docstring, falling back to its
+        metadata description when it has none.
+
+        Args:
+            rule_cls: The rule class to document.
+
+        Returns:
+            A markdown document with a heading, severity, and body.
+        """
+        metadata = rule_cls.metadata
+        # Read __doc__ rather than inspect.getdoc(): getdoc walks the
+        # MRO and would surface an inherited docstring for an
+        # undocumented rule.
+        documentation = inspect.cleandoc(rule_cls.__doc__) if rule_cls.__doc__ else metadata.description
+        return f"# {metadata.name} ({metadata.id})\n\nDefault severity: {metadata.default_severity}\n\n{documentation}"