argusf 0.1.0.dev0__py3-none-any.whl

argusf/analysis/suppression.py

@@ -0,0 +1,92 @@
+"""Marking findings suppressed by config and inline directives."""
+
+import re
+from fnmatch import fnmatch
+from typing import TYPE_CHECKING
+
+from argusf.analysis.rules import RuleRegistry
+from argusf.analysis.rules.selection import ALL_SELECTOR, RuleSelectionResolver
+from argusf.analysis.syntax_errors import SYNTAX_ERROR_CODE
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.config.models import ArgusConfig
+    from argusf.ir.models import Finding, SourceFile
+
+# Example suppression text: ! argusf: ignore[RGUS001]
+_INLINE_PATTERN = re.compile(r"!\s*argusf:\s*ignore\[([^\]]+)\]")
+
+
+class SuppressionFilter:
+    """Marks findings suppressed per config and inline directives."""
+
+    def __init__(self, config: ArgusConfig, source_root: Path) -> None:
+        """Resolve per-file-ignore patterns up front.
+
+        Args:
+            config: Resolved config; its per_file_ignores and rule
+                lists drive suppression.
+            source_root: Root that per-file patterns match against;
+                its parent is used when a single file is given.
+        """
+        self._config = config.lint
+        self._source_root = source_root.parent if source_root.is_file() else source_root
+        self._suppressed_by_pattern = self._resolve_per_file_ignores()
+
+    def apply(self, source_file: SourceFile, findings: list[Finding]) -> None:
+        """Mark matching findings suppressed, in place.
+
+        Applies per-file-ignore patterns and inline `argusf: ignore`
+        directives; syntax-error findings are never suppressed.
+
+        Args:
+            source_file: The file the findings came from.
+            findings: Findings to update; matched ones get
+                `suppressed = True`.
+        """
+        inline_suppressions = self._inline_suppressions(source_file)
+        suppressed_rules = self._per_file_suppressed_rules(source_file)
+
+        for finding in findings:
+            # Syntax errors cannot be suppressed: the code is unknown to
+            # per-file-ignore selectors by construction, but an inline
+            # `! argusf: ignore[ERROR]` would string-match here.
+            if finding.rule_id == SYNTAX_ERROR_CODE:
+                continue
+            if finding.rule_id in suppressed_rules or finding.rule_id in inline_suppressions.get(finding.line, set()):
+                finding.suppressed = True
+
+    def _resolve_per_file_ignores(self) -> dict[str, set[str]]:
+        # Each pattern's selectors are ignore-only, so they resolve
+        # against a select of ALL: the complement of what survives is
+        # suppressed for files matching the pattern. Resolving eagerly
+        # also fails fast on unknown selectors before any file is
+        # analysed.
+        known_rules = set(RuleRegistry.keys())
+        resolver = RuleSelectionResolver()
+        return {
+            pattern: known_rules - resolver.resolve((ALL_SELECTOR,), selectors)
+            for pattern, selectors in self._config.per_file_ignores.items()
+        }
+
+    def _per_file_suppressed_rules(self, source_file: SourceFile) -> set[str]:
+        rel_path = str(source_file.file_path.relative_to(self._source_root))
+        suppressed: set[str] = set()
+        for pattern, rule_ids in self._suppressed_by_pattern.items():
+            if fnmatch(rel_path, pattern):
+                suppressed.update(rule_ids)
+        return suppressed
+
+    def _inline_suppressions(self, source_file: SourceFile) -> dict[int, set[str]]:
+        # A suppression directive applies to findings on the same line
+        # as the comment, e.g. a trailing `GOTO 10 ! argusf:
+        # ignore[RGUS001]`.
+        suppressions: dict[int, set[str]] = {}
+        for comment in source_file.walk_comments():
+            match = _INLINE_PATTERN.search(comment.text)
+            if match is None:
+                continue
+            rule_ids = {rule_id.strip() for rule_id in match.group(1).split(",")}
+            suppressions.setdefault(comment.span.start_row, set()).update(rule_ids)
+        return suppressions

argusf/analysis/syntax_errors.py

@@ -0,0 +1,41 @@
+"""The reserved syntax-error finding and its constants."""
+
+from typing import TYPE_CHECKING
+
+from argusf.ir.models import Finding, Severity, SourceSpan
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# Reserved code for syntax-error findings. Deliberately NOT registered
+# in the RuleRegistry: selectors don't know it (so
+# select/ignore/per-file ignores can never disable it) and no rule
+# produces it — the parser does.
+SYNTAX_ERROR_CODE = "ERROR"
+SYNTAX_ERROR_MESSAGE = "unparseable code"
+# Display name for statistics rows; real rules take theirs from
+# metadata.
+SYNTAX_ERROR_NAME = "syntax-error"
+
+
+def syntax_error_finding(file_path: Path, span: SourceSpan | None) -> Finding:
+    """Build the pseudo-finding for a syntax error.
+
+    Args:
+        file_path: File the error was found in.
+        span: Error location, or None for a whole-file error
+            (reported at 1:1).
+
+    Returns:
+        A finding carrying the reserved syntax-error code.
+    """
+    return Finding(
+        rule_id=SYNTAX_ERROR_CODE,
+        message=SYNTAX_ERROR_MESSAGE,
+        severity=Severity.ERROR,
+        file_path=file_path,
+        line=span.start_row if span else 0,
+        column=span.start_col if span else 0,
+        end_line=span.end_row if span else None,
+        end_column=span.end_col if span else None,
+    )

argusf/autofix/__init__.py

@@ -0,0 +1,26 @@
+"""The autofix stage: applying rule fixes to source."""
+
+from .applier import ApplyOutcome, FixApplier, OverlappingEditsError
+from .context import FixContext, FixMode, build_fix_context, resolve_fix_mode
+from .diff import DiffRenderer
+from .engine import FixEngine, FixOutcome
+from .models import Applicability, Edit, Fix
+from .writer import FileSystemSourceWriter, SourceWriter
+
+__all__ = [
+    "Applicability",
+    "ApplyOutcome",
+    "DiffRenderer",
+    "Edit",
+    "FileSystemSourceWriter",
+    "Fix",
+    "FixApplier",
+    "FixContext",
+    "FixEngine",
+    "FixMode",
+    "FixOutcome",
+    "OverlappingEditsError",
+    "SourceWriter",
+    "build_fix_context",
+    "resolve_fix_mode",
+]

argusf/autofix/applier.py

@@ -0,0 +1,130 @@
+"""Applying the non-overlapping subset of fix edits to source bytes."""
+
+from dataclasses import dataclass
+from itertools import pairwise
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from argusf.autofix.models import Edit, Fix
+    from argusf.ir.models import Finding
+
+
+@dataclass(frozen=True)
+class ApplyOutcome:
+    """The spliced source and the findings whose fixes applied."""
+
+    source: bytes
+    applied: list[Finding]
+
+
+class FixInvariantError(ValueError):
+    """A fix's edits are malformed and cannot be applied to the source.
+
+    Either the edits overlap each other, or an edit's span does not
+    index into the source it applies to. Both are defects the applier
+    cannot resolve by reordering — a rule bug, or a fix built against a
+    different version of the file — so it raises. The fix stage catches
+    this at the file boundary and leaves that one file unfixed rather
+    than aborting the whole run.
+    """
+
+
+class OverlappingEditsError(FixInvariantError):
+    """A single fix's edits overlap each other (a rule bug)."""
+
+    def __init__(self, fix: Fix) -> None:
+        """Build the error for a fix with overlapping edits.
+
+        Args:
+            fix: The fix whose edits overlap.
+        """
+        super().__init__(f"edits within one fix overlap: {fix!r}")
+
+
+class EditOutOfBoundsError(FixInvariantError):
+    """A fix edit's span does not index into its source."""
+
+    def __init__(self, fix: Fix, edit: Edit, source_len: int) -> None:
+        """Build the error for an out-of-bounds edit span.
+
+        Args:
+            fix: The fix the edit belongs to.
+            edit: The edit whose span is out of range.
+            source_len: Length of the source in bytes.
+        """
+        super().__init__(f"fix edit span out of bounds for {source_len}-byte source: {edit.span!r} in {fix!r}")
+
+
+class FixApplier:
+    """Applies the non-overlapping subset of fixes to source.
+
+    Candidate fixes are taken in document order (position of their first
+    edit). A fix whose edits would overlap an already-accepted fix is
+    skipped, not failed: the fix loop re-analyses after applying, so the
+    skipped fix re-emerges next iteration against the new source.
+    """
+
+    def apply(self, source: bytes, findings: Iterable[Finding]) -> ApplyOutcome:
+        """Apply every non-conflicting fix to `source`.
+
+        Fixes are considered in document order; one whose edits
+        overlap an already-accepted fix is skipped (to re-emerge next
+        fix-loop iteration), not failed.
+
+        Args:
+            source: The current source bytes.
+            findings: Findings whose fixes are candidates.
+
+        Returns:
+            The spliced source and the findings that applied.
+
+        Raises:
+            FixInvariantError: On edits malformed within one fix.
+        """
+        candidates = [finding for finding in findings if finding.fix is not None and finding.fix.edits]
+        candidates.sort(key=lambda finding: min(edit.span.start_byte for edit in finding.fix.edits))  # type: ignore[union-attr]
+
+        accepted: list[Edit] = []
+        applied: list[Finding] = []
+        for finding in candidates:
+            fix = finding.fix
+            if fix is None:  # narrowed away above; keeps mypy honest
+                continue
+            edits = sorted(fix.edits, key=lambda edit: (edit.span.start_byte, edit.span.end_byte))
+            self._check_fix_invariants(fix, edits, source)
+            if any(self._conflicts(edit, other) for edit in edits for other in accepted):
+                continue
+            accepted.extend(edits)
+            applied.append(finding)
+
+        return ApplyOutcome(source=self._splice(source, accepted), applied=applied)
+
+    def _check_fix_invariants(self, fix: Fix, sorted_edits: list[Edit], source: bytes) -> None:
+        for previous, current in pairwise(sorted_edits):
+            if self._conflicts(previous, current):
+                raise OverlappingEditsError(fix)
+        # Every edit must index into the source, not just the last by
+        # sort order: end_byte is not monotonic with start_byte, and an
+        # inverted span (start > end) can sit anywhere in the run.
+        for edit in sorted_edits:
+            span = edit.span
+            if span.start_byte > span.end_byte or span.end_byte > len(source):
+                raise EditOutOfBoundsError(fix, edit, len(source))
+
+    def _conflicts(self, a: Edit, b: Edit) -> bool:
+        # Touching edits are fine (half-open intervals); two insertions
+        # at the same point are not — their relative order would be
+        # arbitrary.
+        if a.span.start_byte == a.span.end_byte == b.span.start_byte == b.span.end_byte:
+            return True
+        return a.span.start_byte < b.span.end_byte and b.span.start_byte < a.span.end_byte
+
+    def _splice(self, source: bytes, edits: list[Edit]) -> bytes:
+        # Splicing back-to-front keeps every remaining edit's offsets
+        # valid.
+        result = bytearray(source)
+        for edit in sorted(edits, key=lambda edit: (edit.span.start_byte, edit.span.end_byte), reverse=True):
+            result[edit.span.start_byte : edit.span.end_byte] = edit.content.encode()
+        return bytes(result)

argusf/autofix/context.py

@@ -0,0 +1,82 @@
+"""Fix-run modes and the shared runtime fix context."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from argusf.autofix.models import Applicability, Fix
+
+if TYPE_CHECKING:
+    from argusf.config.models import ArgusConfig
+
+
+class FixMode(StrEnum):
+    """What the fix stage does with findings this run."""
+
+    REPORT = "report"
+    FIX = "fix"
+    FIX_ONLY = "fix_only"
+    DIFF = "diff"
+
+
+def resolve_fix_mode(config: ArgusConfig, *, diff: bool) -> FixMode:
+    """Resolve the fix mode from config and the --diff flag.
+
+    Args:
+        config: Resolved config (its fix and fix_only flags).
+        diff: Whether --diff was passed.
+
+    Returns:
+        The mode, with diff > fix_only > fix > report precedence.
+    """
+    # --diff implies fix-only reporting and never writes; fix_only
+    # implies fix.
+    if diff:
+        return FixMode.DIFF
+    if config.fix_only:
+        return FixMode.FIX_ONLY
+    if config.fix:
+        return FixMode.FIX
+    return FixMode.REPORT
+
+
+def build_fix_context(config: ArgusConfig, *, diff: bool) -> FixContext:
+    """Build the run's FixContext from config and --diff.
+
+    Args:
+        config: Resolved config supplying unsafe_fixes/show_fixes.
+        diff: Whether --diff was passed.
+
+    Returns:
+        The fix context for the run.
+    """
+    return FixContext(
+        mode=resolve_fix_mode(config, diff=diff),
+        unsafe_fixes=config.unsafe_fixes,
+        show_fixes=config.show_fixes,
+    )
+
+
+@dataclass(frozen=True)
+class FixContext:
+    """Runtime fix settings shared by the engine and reporters."""
+
+    mode: FixMode = FixMode.REPORT
+    unsafe_fixes: bool = False
+    show_fixes: bool = False
+
+    @property
+    def writes_files(self) -> bool:
+        """Whether this mode writes fixed files back to disk."""
+        return self.mode in (FixMode.FIX, FixMode.FIX_ONLY)
+
+    def applies(self, fix: Fix) -> bool:
+        """Whether the fix is applicable at this run's safety level.
+
+        Also the [*] marker predicate in reports: deliberately
+        independent of mode, so a plain report marks exactly what --fix
+        would apply.
+        """
+        if fix.applicability is Applicability.SAFE:
+            return True
+        return fix.applicability is Applicability.UNSAFE and self.unsafe_fixes

argusf/autofix/diff.py

@@ -0,0 +1,39 @@
+"""Rendering fix results as a unified diff."""
+
+import difflib
+from pathlib import Path
+
+
+class DiffRenderer:
+    """Renders what a fix run would change as a unified diff.
+
+    Headers carry the bare path on both sides (no a/ b/ prefixes),
+    relative to the working directory when possible.
+    """
+
+    def render(self, path: Path, original: bytes, fixed: bytes) -> str:
+        """Render the change from `original` to `fixed` as a diff.
+
+        Args:
+            path: File path, shown bare in the diff headers.
+            original: Bytes before fixing.
+            fixed: Bytes after fixing.
+
+        Returns:
+            A unified diff, empty when the two are identical.
+        """
+        label = self._label(path)
+        return "".join(
+            difflib.unified_diff(
+                original.decode(errors="replace").splitlines(keepends=True),
+                fixed.decode(errors="replace").splitlines(keepends=True),
+                fromfile=label,
+                tofile=label,
+            )
+        )
+
+    def _label(self, path: Path) -> str:
+        try:
+            return str(path.relative_to(Path.cwd()))
+        except ValueError:
+            return str(path)

argusf/autofix/edits.py

@@ -0,0 +1,31 @@
+"""Edit constructors: how rules express a source change.
+
+Every modification is one shape — replace the bytes a span covers with
+the supplied content — so these constructors only differ in how they
+frame that: `insertion` replaces a zero-width span, `deletion` replaces
+with nothing, `replacement` swaps content in place. The measurement
+helpers for choosing the right span live in `source.py`.
+"""
+
+from typing import TYPE_CHECKING
+
+from argusf.autofix.models import Edit
+from argusf.autofix.source import span_between
+
+if TYPE_CHECKING:
+    from argusf.ir.models import SourceSpan
+
+
+def insertion(source: bytes, at_byte: int, content: str) -> Edit:
+    """Insert content at a byte offset (a zero-width replacement)."""
+    return Edit(span=span_between(source, at_byte, at_byte), content=content)
+
+
+def deletion(span: SourceSpan) -> Edit:
+    """Remove the bytes the span covers."""
+    return Edit(span=span, content="")
+
+
+def replacement(span: SourceSpan, content: str) -> Edit:
+    """Swap the bytes the span covers for the supplied content."""
+    return Edit(span=span, content=content)

argusf/autofix/engine.py

@@ -0,0 +1,192 @@
+"""The autofix stage: the fix loop and per-mode outcomes."""
+
+from collections import Counter
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol
+
+from argusf.analysis.syntax_errors import SYNTAX_ERROR_CODE
+from argusf.autofix.applier import FixApplier, FixInvariantError
+from argusf.autofix.context import FixContext, FixMode
+from argusf.autofix.diff import DiffRenderer
+from argusf.autofix.writer import FileSystemSourceWriter
+from argusf.constants import MAX_FIX_ITERATIONS
+
+if TYPE_CHECKING:
+    from argusf.diagnostics import Diagnostics
+    from argusf.hashing.hash import Hasher
+    from argusf.ir.models import Finding, SourceFile, SourceFileMetadata
+    from argusf.parser.backend import ParsingEngine
+
+
+class Analyser(Protocol):
+    """Structural stand-in for the analysis engine.
+
+    Importing the real class here would close an import cycle
+    (analysis -> rules -> autofix models), and the fix loop only needs
+    "findings for a parsed file" anyway.
+    """
+
+    def analyse(self, source_file: SourceFile) -> list[Finding]:
+        """Return the findings for a parsed source file."""
+        ...
+
+
+@dataclass(frozen=True)
+class FixOutcome:
+    """What the fix stage decided for one file.
+
+    findings/metadata are what the caller should report and cache: the
+    post-fix state after a write, the untouched original state otherwise
+    (including --diff runs, where the disk never changes).
+    """
+
+    findings: list[Finding]
+    metadata: SourceFileMetadata
+    fixed_by_rule: Counter[str]
+    diff: str | None
+    changed: bool
+
+
+class FixEngine:
+    """The autofix stage of a run, self-contained per file.
+
+    Owns everything between "findings are known" and "results are
+    reported": fix eligibility, the apply -> re-parse -> re-lint loop,
+    writing fixed source back (or rendering a diff instead), and
+    deciding which findings/metadata the caller should report and cache
+    for each mode. In REPORT mode it is a pass-through.
+
+    Source bytes are read here, lazily, only once a file actually has
+    applicable fixes — the run's other stages carry lean metadata only.
+    A content-hash check guards the read: edits computed against one
+    version of a file are never applied to another.
+
+    The fix-only moving parts (applier, writer, diff renderer) are
+    composed here rather than injected: nothing outside the autofix
+    stage has any business varying them. Injected collaborators are the
+    ones shared with the rest of the run.
+    """
+
+    def __init__(
+        self,
+        parsing_engine: ParsingEngine,
+        analyser: Analyser,
+        hasher: Hasher,
+        context: FixContext,
+        diagnostics: Diagnostics,
+    ) -> None:
+        """Compose the fix stage from its collaborators.
+
+        Args:
+            parsing_engine: Re-parses fixed source in memory.
+            analyser: Re-analyses re-parsed source each loop.
+            hasher: Verifies source identity before editing.
+            context: The run's fix mode and safety settings.
+            diagnostics: Channel for skipped-file notices.
+        """
+        self._parsing_engine = parsing_engine
+        self._analyser = analyser
+        self._hasher = hasher
+        self._context = context
+        self._diagnostics = diagnostics
+        self._applier = FixApplier()
+        self._source_writer = FileSystemSourceWriter(hasher)
+        self._diff_renderer = DiffRenderer()
+
+    def process(self, file: SourceFileMetadata, findings: list[Finding]) -> FixOutcome:
+        """Run the fix stage for one file.
+
+        In REPORT mode (or when nothing is eligible) passes findings
+        through unchanged. Otherwise runs the fix loop, then writes
+        the file (FIX/FIX_ONLY) or renders a diff (DIFF), leaving
+        disk and cache consistent per mode.
+
+        Args:
+            file: Identity metadata of the file.
+            findings: The file's current findings.
+
+        Returns:
+            The per-mode fix outcome.
+        """
+        if self._context.mode is FixMode.REPORT or not self._eligible(findings):
+            return self._passthrough(file, findings)
+        original = self._read_source(file)
+        if original is None:
+            return self._passthrough(file, findings)
+        try:
+            source, final_findings, fixed_by_rule = self._fix_loop(file, original, findings)
+        except FixInvariantError as error:
+            # A malformed fix (a rule bug, or a fix stale against this
+            # source) must not abort the whole run: leave this one file
+            # unfixed, on disk untouched, and surface it as a
+            # diagnostic.
+            self._diagnostics.emit(f"skipping fixes for {file.file_path}: {error}")
+            return self._passthrough(file, findings)
+        if not fixed_by_rule:
+            return self._passthrough(file, findings)
+        if self._context.writes_files:
+            metadata = self._source_writer.write(file.file_path, source)
+            return FixOutcome(
+                findings=final_findings, metadata=metadata, fixed_by_rule=fixed_by_rule, diff=None, changed=True
+            )
+        # DIFF mode: the disk is untouched, so the original state is
+        # what gets reported and cached; the rendered diff and the
+        # would-fix counts carry the outcome.
+        diff = self._diff_renderer.render(file.file_path, original, source)
+        return FixOutcome(findings=findings, metadata=file, fixed_by_rule=fixed_by_rule, diff=diff, changed=False)
+
+    def _passthrough(self, file: SourceFileMetadata, findings: list[Finding]) -> FixOutcome:
+        return FixOutcome(findings=findings, metadata=file, fixed_by_rule=Counter(), diff=None, changed=False)
+
+    def _read_source(self, file: SourceFileMetadata) -> bytes | None:
+        """Return the bytes the findings were computed from, or None.
+
+        A file that vanished, or whose content no longer matches the
+        hash the findings were derived from, is left alone (returns
+        None): byte edits against drifted content would corrupt it.
+        """
+        try:
+            source = file.file_path.read_bytes()
+        except OSError:
+            self._diagnostics.emit(f"could not read {file.file_path}, not fixing it")
+            return None
+        if self._hasher.hash_bytes(source) != file.content_hash:
+            self._diagnostics.emit(f"{file.file_path} changed since it was analysed, not fixing it")
+            return None
+        return source
+
+    def _fix_loop(
+        self, file: SourceFileMetadata, source: bytes, findings: list[Finding]
+    ) -> tuple[bytes, list[Finding], Counter[str]]:
+        fixed_by_rule: Counter[str] = Counter()
+        for _ in range(MAX_FIX_ITERATIONS):
+            eligible = self._eligible(findings)
+            if not eligible:
+                return source, findings, fixed_by_rule
+            outcome = self._applier.apply(source, eligible)
+            if not outcome.applied:
+                return source, findings, fixed_by_rule
+            fixed_by_rule.update(finding.rule_id for finding in outcome.applied)
+            source = outcome.source
+            findings = self._recompute_findings(file, source)
+        self._diagnostics.emit(f"autofix did not converge after {MAX_FIX_ITERATIONS} iterations: {file.file_path}")
+        return source, findings, fixed_by_rule
+
+    def _recompute_findings(self, file: SourceFileMetadata, source: bytes) -> list[Finding]:
+        """Re-parse and re-analyse the fixed source in memory.
+
+        Fixes changed the source, so the findings are recomputed for
+        the file as it now stands.
+        """
+        return self._analyser.analyse(self._parsing_engine.parse_source(file.file_path, source))
+
+    def _eligible(self, findings: list[Finding]) -> list[Finding]:
+        # A file with syntax errors is never fixed: spans inside and
+        # after the broken region are not trustworthy enough to edit by.
+        if any(finding.rule_id == SYNTAX_ERROR_CODE for finding in findings):
+            return []
+        return [
+            finding
+            for finding in findings
+            if not finding.suppressed and finding.fix is not None and self._context.applies(finding.fix)
+        ]

argusf/autofix/models.py

@@ -0,0 +1,39 @@
+"""The fix data model: Applicability, Edit, and Fix."""
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from argusf.ir.models import SourceSpan
+
+
+class Applicability(StrEnum):
+    """How safe a fix is to apply automatically."""
+
+    SAFE = "safe"
+    UNSAFE = "unsafe"
+    DISPLAY = "display"
+
+
+@dataclass(frozen=True)
+class Edit:
+    """A single edit: replace a span's bytes with content."""
+
+    # A zero-width span (start_byte == end_byte) is an insertion; empty
+    # content is a deletion. Byte offsets drive application; the row/col
+    # fields feed reporting.
+    span: SourceSpan
+    content: str
+
+
+@dataclass(frozen=True)
+class Fix:
+    """A fix: an applicability, its edits, and a message."""
+
+    applicability: Applicability
+    # Edits within one fix must not overlap; the applier treats that as
+    # a rule bug. Fixes from different findings may overlap — the fix
+    # loop defers the loser to its next iteration.
+    edits: tuple[Edit, ...]
+    message: str | None = None