argusf 0.1.0.dev0__py3-none-any.whl

argusf/autofix/source.py

@@ -0,0 +1,68 @@
+"""Measurement helpers over raw source bytes.
+
+Where lines begin and end, what a span covers, how a line is indented.
+Nothing here modifies anything — the edit constructors in `edits.py`
+build on these.
+
+Byte offsets are the working coordinates (the same ones tree-sitter
+spans use); rows and columns are derived so produced spans stay
+consistent with parser-produced ones.
+"""
+
+from argusf.ir.models import SourceSpan
+
+
+def line_start(source: bytes, byte_offset: int) -> int:
+    """Offset of the first byte of the line containing byte_offset."""
+    return source.rfind(b"\n", 0, byte_offset) + 1
+
+
+def line_end(source: bytes, byte_offset: int) -> int:
+    """Offset just past the line containing byte_offset."""
+    index = source.find(b"\n", byte_offset)
+    return len(source) if index == -1 else index + 1
+
+
+def line_indent(source: bytes, byte_offset: int) -> str:
+    """The leading whitespace of the line containing byte_offset."""
+    start = line_start(source, byte_offset)
+    index = start
+    while index < len(source) and source[index : index + 1] in (b" ", b"\t"):
+        index += 1
+    return source[start:index].decode("ascii")
+
+
+def span_between(source: bytes, start_byte: int, end_byte: int) -> SourceSpan:
+    """A span over [start_byte, end_byte) with derived rows/cols."""
+    start_row = source.count(b"\n", 0, start_byte)
+    end_row = start_row + source.count(b"\n", start_byte, end_byte)
+    return SourceSpan(
+        start_row=start_row,
+        start_col=start_byte - line_start(source, start_byte),
+        end_row=end_row,
+        end_col=end_byte - line_start(source, end_byte),
+        start_byte=start_byte,
+        end_byte=end_byte,
+    )
+
+
+def full_lines_span(source: bytes, span: SourceSpan) -> SourceSpan:
+    """The span widened to whole lines, trailing newline included."""
+    start = line_start(source, span.start_byte)
+    end = line_end(source, max(span.start_byte, span.end_byte - 1))
+    return span_between(source, start, end)
+
+
+def span_fits(source: bytes, span: SourceSpan) -> bool:
+    """Whether the span's byte range indexes into this source at all.
+
+    A rule offering a fix must check this first: a hand-built SourceFile
+    without its bytes (or one whose spans disagree with the bytes)
+    should yield a finding without a fix, never an out-of-range edit.
+    """
+    return span.end_byte <= len(source)
+
+
+def slice_of(source: bytes, span: SourceSpan) -> bytes:
+    """The bytes the span covers."""
+    return source[span.start_byte : span.end_byte]

argusf/autofix/writer.py

@@ -0,0 +1,53 @@
+"""Writing fixed source back to disk with fresh identity."""
+
+from typing import TYPE_CHECKING, Protocol
+
+from argusf.ir.models import SourceFileMetadata
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from argusf.hashing.hash import Hasher
+
+
+class SourceWriter(Protocol):
+    """Persists fixed source and returns its new identity."""
+
+    def write(self, path: Path, content: bytes) -> SourceFileMetadata:
+        """Persist content at path; return the file's new identity."""
+        ...
+
+
+class FileSystemSourceWriter(SourceWriter):
+    """Writes fixed source back in place.
+
+    Re-stats and re-hashes after the write so the caller can cache the
+    fixed file's findings against its real post-fix identity.
+    """
+
+    def __init__(self, hasher: Hasher) -> None:
+        """Build the writer with a hasher for post-write identity.
+
+        Args:
+            hasher: Hashes written bytes for the returned metadata.
+        """
+        self._hasher = hasher
+
+    def write(self, path: Path, content: bytes) -> SourceFileMetadata:
+        """Write `content` to `path` and return its new identity.
+
+        Args:
+            path: File to overwrite.
+            content: Fixed bytes to write.
+
+        Returns:
+            Metadata (size/mtime/hash) of the file after writing.
+        """
+        path.write_bytes(content)
+        stat = path.stat()
+        return SourceFileMetadata(
+            file_path=path,
+            size=stat.st_size,
+            mtime=stat.st_mtime,
+            content_hash=self._hasher.hash_bytes(content),
+        )

argusf/cache/__init__.py

@@ -0,0 +1,5 @@
+"""Persistent caching of per-file findings."""
+
+from .backend import CacheBackend, Cacher
+
+__all__ = ["CacheBackend", "Cacher"]

argusf/cache/backend.py

@@ -0,0 +1,294 @@
+"""msgpack-backed cache of per-file findings keyed by identity."""
+
+import hashlib
+import json
+import pathlib
+import shutil
+import tempfile
+from dataclasses import asdict, dataclass, field
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+import msgpack
+
+from argusf.autofix.models import Applicability, Edit, Fix
+from argusf.hashing.hash import HashBackend, Hasher
+from argusf.ir.models import Finding, Severity, SourceFileMetadata, SourceSpan
+
+if TYPE_CHECKING:
+    from argusf.config.models import ArgusConfig, LintConfig
+    from argusf.diagnostics import Diagnostics
+
+
+def _settings_fingerprint(lint: LintConfig) -> str:
+    """Stably serialise the analysis-affecting lint settings.
+
+    Reordering fields within lists (e.g. `ignore = ["B", "A"]` vs
+    `["A", "B"]`) costs a one-time re-analysis but is the conservative
+    correct default. New LintConfig fields are picked up automatically
+    via asdict.
+    """
+    return json.dumps(asdict(lint), sort_keys=True)
+
+
+@dataclass
+class CachedFileEntry:
+    """A cached file's identity metadata and its findings."""
+
+    metadata: SourceFileMetadata
+    findings: list[Finding] = field(default_factory=list)
+
+
+@runtime_checkable
+class Cacher(Protocol):
+    """Stores and retrieves per-file findings across runs."""
+
+    def get(self, file: SourceFileMetadata) -> CachedFileEntry | None:
+        """Return a cache entry if it exists and is still valid."""
+        ...
+
+    def put(self, file: SourceFileMetadata, findings: list[Finding]) -> None:
+        """Store a cache entry in memory for the given file."""
+        ...
+
+    def invalidate(self, file: SourceFileMetadata) -> None:
+        """Remove a cache entry from the cache."""
+        ...
+
+    def clear(self) -> None:
+        """Remove cache and all contained entries (if exists)."""
+        ...
+
+    def write_to_cache(self) -> None:
+        """Write all new entries from memory to the cache."""
+        ...
+
+    def _is_cached_entry_valid(self, file: SourceFileMetadata, cache_entry: CachedFileEntry) -> bool:
+        """Compare file and cache entry metadata for validity."""
+        ...
+
+
+def _span_to_dict(span: SourceSpan) -> dict[str, Any]:
+    return {
+        "start_row": span.start_row,
+        "start_col": span.start_col,
+        "end_row": span.end_row,
+        "end_col": span.end_col,
+        "start_byte": span.start_byte,
+        "end_byte": span.end_byte,
+    }
+
+
+def _span_from_dict(data: dict[str, Any]) -> SourceSpan:
+    return SourceSpan(
+        start_row=data["start_row"],
+        start_col=data["start_col"],
+        end_row=data["end_row"],
+        end_col=data["end_col"],
+        start_byte=data["start_byte"],
+        end_byte=data["end_byte"],
+    )
+
+
+def _fix_to_dict(fix: Fix) -> dict[str, Any]:
+    return {
+        "applicability": fix.applicability.value,
+        "edits": [{"span": _span_to_dict(edit.span), "content": edit.content} for edit in fix.edits],
+        "message": fix.message,
+    }
+
+
+def _fix_from_dict(data: dict[str, Any]) -> Fix:
+    return Fix(
+        applicability=Applicability(data["applicability"]),
+        edits=tuple(Edit(span=_span_from_dict(edit["span"]), content=edit["content"]) for edit in data["edits"]),
+        message=data["message"],
+    )
+
+
+def _finding_to_dict(finding: Finding) -> dict[str, Any]:
+    return {
+        "rule_id": finding.rule_id,
+        "message": finding.message,
+        "severity": finding.severity.value,
+        "file_path": str(finding.file_path),
+        "line": finding.line,
+        "column": finding.column,
+        "end_line": finding.end_line,
+        "end_column": finding.end_column,
+        "suggestion": finding.suggestion,
+        "fix": None if finding.fix is None else _fix_to_dict(finding.fix),
+        "suppressed": finding.suppressed,
+    }
+
+
+def _finding_from_dict(data: dict[str, Any]) -> Finding:
+    # data["fix"], not data.get("fix"): an entry written before the fix
+    # field existed raises KeyError, which get() treats as format drift
+    # and rebuilds — restoring it as fix-less would silently drop fixes.
+    return Finding(
+        rule_id=data["rule_id"],
+        message=data["message"],
+        severity=Severity(data["severity"]),
+        file_path=pathlib.Path(data["file_path"]),
+        line=data["line"],
+        column=data["column"],
+        end_line=data["end_line"],
+        end_column=data["end_column"],
+        suggestion=data["suggestion"],
+        fix=None if data["fix"] is None else _fix_from_dict(data["fix"]),
+        suppressed=data["suppressed"],
+    )
+
+
+class CacheBackend(Cacher):
+    """Caches per-file findings alongside file metadata.
+
+    Entries are serialised with msgpack since the findings list is
+    variable in size and content.
+    """
+
+    def __init__(
+        self,
+        argus_version: str,
+        python_version: str,
+        config: ArgusConfig,
+        diagnostics: Diagnostics,
+        hash_backend: Hasher | None = None,
+    ) -> None:
+        """Configure the cache directory from version and settings.
+
+        Args:
+            argus_version: Running argusf version (part of the cache
+                version key).
+            python_version: Running Python version (part of the key).
+            config: Resolved config providing the cache directory and
+                the lint settings fingerprint.
+            diagnostics: Channel for reporting corrupt cache entries.
+            hash_backend: Hasher for the version key; defaults to a
+                fresh HashBackend.
+        """
+        self._argus_version = argus_version
+        self._python_version = python_version
+        self._config = config
+        self._diagnostics = diagnostics
+
+        self._hash_backend = hash_backend or HashBackend()
+        cache_version = self._hash_backend.get_cache_version_hash(
+            argus_version, python_version, _settings_fingerprint(config.lint)
+        )
+        self._cache_dir_path = pathlib.Path(f"{config.cache_dir}/{cache_version}")
+        self._new_cache_entries: list[CachedFileEntry] = []
+
+    def _cache_file_path(self, file: SourceFileMetadata) -> pathlib.Path:
+        name = hashlib.sha256(str(file.file_path).encode()).hexdigest()
+
+        return self._cache_dir_path / name
+
+    def _pack(self, entry: CachedFileEntry) -> bytes:
+        payload = {
+            "file_path": str(entry.metadata.file_path),
+            "size": entry.metadata.size,
+            "mtime": entry.metadata.mtime,
+            "content_hash": entry.metadata.content_hash,
+            "findings": [_finding_to_dict(finding) for finding in entry.findings],
+        }
+
+        packed: bytes = msgpack.packb(payload)
+        return packed
+
+    def _unpack(self, data: bytes) -> CachedFileEntry:
+        payload = msgpack.unpackb(data)
+
+        return CachedFileEntry(
+            metadata=SourceFileMetadata(
+                file_path=pathlib.Path(payload["file_path"]),
+                size=payload["size"],
+                mtime=payload["mtime"],
+                content_hash=payload["content_hash"],
+            ),
+            findings=[_finding_from_dict(finding) for finding in payload["findings"]],
+        )
+
+    def _is_cached_entry_valid(self, file: SourceFileMetadata, cache_entry: CachedFileEntry) -> bool:
+        """Whether the cached entry still matches the file's identity.
+
+        Dataclass equality compares path/size/mtime/content_hash —
+        exactly the identity and validation fields. The caller's
+        metadata was populated by the collector from the same read the
+        parser sees, closing the TOCTOU window between cache validation
+        and parsing.
+        """
+        return file == cache_entry.metadata
+
+    def get(self, file: SourceFileMetadata) -> CachedFileEntry | None:
+        """Return a valid cache entry for `file`, or None.
+
+        Returns None when no entry exists, the stored bytes are
+        unreadable (corrupt or format drift — the entry is dropped),
+        or the stored metadata no longer matches `file`.
+
+        Args:
+            file: Identity metadata of the file to look up.
+
+        Returns:
+            The cached entry when present and still valid, else None.
+        """
+        cache_path = self._cache_file_path(file)
+        if not cache_path.exists():
+            return None
+
+        try:
+            entry = self._unpack(cache_path.read_bytes())
+        except KeyError, TypeError, ValueError:
+            # Cache entry is unreadable: corrupted msgpack bytes,
+            # truncated write, or format drift between versions. Drop it
+            # so the next analysis writes a fresh entry over the top.
+            self._diagnostics.emit(f"cache entry corrupt, rebuilding: {file.file_path}")
+            self.invalidate(file)
+            return None
+
+        return entry if self._is_cached_entry_valid(file, entry) else None
+
+    def put(self, file: SourceFileMetadata, findings: list[Finding]) -> None:
+        """Stage a cache entry in memory for `file`.
+
+        The entry is not persisted until `write_to_cache`.
+
+        Args:
+            file: Identity metadata to key the entry by.
+            findings: Findings to cache for the file.
+        """
+        self._new_cache_entries.append(CachedFileEntry(metadata=file, findings=findings))
+
+    def write_to_cache(self) -> None:
+        """Persist all staged entries to the cache directory.
+
+        Entries are written to a temporary directory and then moved
+        into place, so a crash mid-write never leaves a partial
+        entry. Clears the in-memory staging list.
+        """
+        with tempfile.TemporaryDirectory() as tmp:
+            tmp_path = pathlib.Path(tmp)
+            staged: list[tuple[pathlib.Path, pathlib.Path]] = []
+            for entry in self._new_cache_entries:
+                name = hashlib.sha256(str(entry.metadata.file_path).encode()).hexdigest()
+                staged_file = tmp_path / name
+                staged_file.write_bytes(self._pack(entry))
+                staged.append((staged_file, self._cache_dir_path / name))
+            self._cache_dir_path.mkdir(parents=True, exist_ok=True)  # no-op if already exists
+            for src, dst in staged:
+                shutil.move(str(src), dst)
+
+        self._new_cache_entries.clear()
+
+    def invalidate(self, file: SourceFileMetadata) -> None:
+        """Delete the on-disk cache entry for `file`, if any.
+
+        Args:
+            file: Identity metadata of the entry to remove.
+        """
+        self._cache_file_path(file).unlink(missing_ok=True)
+
+    def clear(self) -> None:
+        """Remove the entire cache directory for this version."""
+        shutil.rmtree(self._cache_dir_path, ignore_errors=True)