code-standards 7.0.0__py3-none-any.whl

sarj_standards/libs/diagnostics/serialize.py

@@ -0,0 +1,290 @@
+from __future__ import annotations
+
+from heapq import nsmallest
+import json
+from urllib.parse import quote
+
+from .models import AnalysisReport, Diagnostic, Fix, FixSafety, Location, Severity, TextEdit
+
+
+_GITHUB_ANNOTATION_LIMIT = 10
+
+
+def to_json(report: AnalysisReport, *, indent: int | None = 2) -> str:
+    return json.dumps(report.as_dict(), indent=indent, sort_keys=True) + "\n"
+
+
+def to_sarif(report: AnalysisReport) -> str:
+    rules = _sarif_rules(report)
+    payload: dict[str, object] = {
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "code-standards",
+                        "informationUri": "https://github.com/sarj-ai/code-standards",
+                        "rules": rules,
+                    }
+                },
+                "results": [_sarif_result(item) for item in report.diagnostics],
+                "columnKind": "utf16CodeUnits",
+                "invocations": [
+                    {
+                        "executionSuccessful": report.completion.value == "complete",
+                        "toolExecutionNotifications": [
+                            {"descriptor": {"id": issue.kind}, "message": {"text": issue.message}, "level": "error"}
+                            for issue in report.issues
+                        ]
+                        + [
+                            {
+                                "descriptor": {"id": "coverage-notice"},
+                                "message": {"text": _coverage_line(item.source, item.reason, item.file_count)},
+                                "level": "error" if item.blocking else "note",
+                                "properties": {"disposition": item.disposition.value},
+                            }
+                            for item in report.coverage
+                        ],
+                    }
+                ],
+            }
+        ],
+    }
+    return json.dumps(payload, indent=2, sort_keys=True) + "\n"
+
+
+def to_text(report: AnalysisReport) -> str:
+    lines = [_text_diagnostic(item) for item in report.diagnostics]
+    lines.extend(f"{issue.source}: {issue.kind}: {issue.message}" for issue in report.issues)
+    lines.extend(_coverage_line(item.source, item.reason, item.file_count) for item in report.coverage)
+    lines.append(_summary(report))
+    return "\n".join(lines) + "\n"
+
+
+def to_github(report: AnalysisReport, *, max_annotations_per_level: int = _GITHUB_ANNOTATION_LIMIT) -> str:
+    if not 0 <= max_annotations_per_level <= _GITHUB_ANNOTATION_LIMIT:
+        msg = "max_annotations_per_level must be between 0 and 10"
+        raise ValueError(msg)
+    issues = [
+        f"::error title={_github_property(f'{issue.source}/{issue.kind}')}::{_github_message(issue.message)}"
+        for issue in report.issues[:max_annotations_per_level]
+    ]
+    counts = dict.fromkeys(Severity, 0)
+    for tool in report.tools:
+        for diagnostic in tool.diagnostics:
+            counts[diagnostic.severity] += 1
+    error_budget = max_annotations_per_level - len(issues)
+    selected = {
+        severity: nsmallest(
+            error_budget if severity is Severity.ERROR else max_annotations_per_level,
+            (diagnostic for tool in report.tools for diagnostic in tool.diagnostics if diagnostic.severity is severity),
+            key=_github_priority,
+        )
+        for severity in Severity
+    }
+    lines = [
+        *issues,
+        *(_github_diagnostic(item) for item in selected[Severity.ERROR]),
+        *(_github_diagnostic(item) for item in selected[Severity.WARNING]),
+        *(_github_diagnostic(item) for item in selected[Severity.INFO]),
+    ]
+    omitted = (
+        max(0, len(report.issues) + counts[Severity.ERROR] - max_annotations_per_level)
+        + max(0, counts[Severity.WARNING] - max_annotations_per_level)
+        + max(0, counts[Severity.INFO] - max_annotations_per_level)
+    )
+    if omitted:
+        lines.append(
+            f"code-standards: {omitted} annotation(s) omitted by GitHub's per-level limits; "
+            "use JSON or SARIF for the complete report"
+        )
+    lines.extend(_coverage_line(item.source, item.reason, item.file_count) for item in report.coverage)
+    lines.append(_summary(report))
+    return "\n".join(lines) + "\n"
+
+
+def _github_priority(diagnostic: Diagnostic) -> tuple[object, ...]:
+    severity = {Severity.ERROR: 0, Severity.WARNING: 1, Severity.INFO: 2}[diagnostic.severity]
+    location = diagnostic.location
+    position = location.region.start if location.region is not None else location.position
+    return (
+        severity,
+        location.path,
+        -1 if position is None else position.line,
+        -1 if position is None else position.character,
+        diagnostic.source,
+        diagnostic.code,
+        diagnostic.message,
+    )
+
+
+def _text_diagnostic(diagnostic: Diagnostic) -> str:
+    position = (
+        diagnostic.location.region.start if diagnostic.location.region is not None else diagnostic.location.position
+    )
+    suffix = "" if position is None else f":{position.line + 1}:{position.character + 1}"
+    return (
+        f"{diagnostic.location.path}{suffix}: {diagnostic.severity.value} "
+        f"{diagnostic.code} {diagnostic.message} [{diagnostic.source}]"
+    )
+
+
+def _github_diagnostic(diagnostic: Diagnostic) -> str:
+    level = "notice" if diagnostic.severity is Severity.INFO else diagnostic.severity.value
+    properties: list[str] = []
+    position = (
+        diagnostic.location.region.start if diagnostic.location.region is not None else diagnostic.location.position
+    )
+    if position is not None:
+        properties.extend((f"file={_github_property(diagnostic.location.path)}", f"line={position.line + 1}"))
+        region = diagnostic.location.region
+        if region is None:
+            properties.append(f"col={position.character + 1}")
+        elif region.end.line == region.start.line:
+            properties.extend(
+                (
+                    f"col={position.character + 1}",
+                    f"endLine={region.end.line + 1}",
+                    f"endColumn={region.end.character + 1}",
+                )
+            )
+        else:
+            properties.append(f"endLine={region.end.line + 1}")
+    properties.append(f"title={_github_property(f'{diagnostic.source}/{diagnostic.code}')}")
+    message = diagnostic.message if position is not None else f"{diagnostic.location.path}: {diagnostic.message}"
+    return f"::{level} {','.join(properties)}::{_github_message(message)}"
+
+
+def _github_message(value: str) -> str:
+    return value.replace("%", "%25").replace("\r", "%0D").replace("\n", "%0A")
+
+
+def _github_property(value: str) -> str:
+    return _github_message(value).replace(":", "%3A").replace(",", "%2C")
+
+
+def _summary(report: AnalysisReport) -> str:
+    counts = dict.fromkeys(Severity, 0)
+    for tool in report.tools:
+        for diagnostic in tool.diagnostics:
+            counts[diagnostic.severity] += 1
+    return (
+        f"code-standards: {counts[Severity.ERROR]} error(s), {counts[Severity.WARNING]} warning(s), "
+        f"{counts[Severity.INFO]} notice(s), {len(report.issues)} execution issue(s)"
+    )
+
+
+def _coverage_line(source: str, reason: str, file_count: int) -> str:
+    return f"code-standards coverage: {source} did not analyze {file_count} selected file(s): {reason}"
+
+
+def _sarif_rules(report: AnalysisReport) -> list[dict[str, object]]:
+    by_code: dict[tuple[str, str], Diagnostic] = {}
+    for diagnostic in report.diagnostics:
+        by_code.setdefault((diagnostic.source, diagnostic.code), diagnostic)
+    return [
+        {
+            "id": _sarif_rule_id(item),
+            "name": item.rule_id or code,
+            "shortDescription": {"text": item.help or item.rule_id or code},
+            **({"helpUri": item.help_url} if item.help_url is not None else {}),
+        }
+        for (_source, code), item in sorted(by_code.items())
+    ]
+
+
+def _sarif_result(diagnostic: Diagnostic) -> dict[str, object]:
+    location = diagnostic.location
+    physical: dict[str, object] = {"artifactLocation": {"uri": quote(location.path, safe="/")}}
+    if location.region is not None:
+        physical["region"] = {
+            "startLine": location.region.start.line + 1,
+            "startColumn": location.region.start.character + 1,
+            "endLine": location.region.end.line + 1,
+            "endColumn": location.region.end.character + 1,
+        }
+    elif location.position is not None:
+        physical["region"] = {
+            "startLine": location.position.line + 1,
+            "startColumn": location.position.character + 1,
+        }
+    result: dict[str, object] = {
+        "ruleId": _sarif_rule_id(diagnostic),
+        "level": _sarif_level(diagnostic.severity),
+        "message": {"text": diagnostic.message},
+        "locations": [{"physicalLocation": physical}],
+        "properties": {
+            "source": diagnostic.source,
+            "code": diagnostic.code,
+            "repositoryRoot": ".",
+            **({"tags": list(diagnostic.tags)} if diagnostic.tags else {}),
+            **({"notes": list(diagnostic.notes)} if diagnostic.notes else {}),
+        },
+    }
+    if diagnostic.fingerprint is not None:
+        result["partialFingerprints"] = {"sarj/v1": diagnostic.fingerprint}
+    safe_fixes = tuple(fix for fix in diagnostic.fixes if fix.safety is FixSafety.SAFE)
+    if safe_fixes:
+        result["fixes"] = [_sarif_fix(fix) for fix in safe_fixes]
+    if diagnostic.related:
+        result["relatedLocations"] = [
+            {"message": {"text": item.label}, "physicalLocation": _sarif_physical(item.location)}
+            for item in diagnostic.related
+        ]
+    return result
+
+
+def _sarif_fix(fix: Fix) -> dict[str, object]:
+    grouped: dict[str, list[TextEdit]] = {}
+    for edit in fix.edits:
+        grouped.setdefault(edit.location.path, []).append(edit)
+    return {
+        "description": {"text": fix.title},
+        "artifactChanges": [
+            {
+                "artifactLocation": {"uri": quote(path, safe="/")},
+                "replacements": [
+                    {
+                        "deletedRegion": _sarif_region(edit.location),
+                        "insertedContent": {"text": edit.replacement},
+                    }
+                    for edit in edits
+                ],
+            }
+            for path, edits in sorted(grouped.items())
+        ],
+    }
+
+
+def _sarif_physical(location: Location) -> dict[str, object]:
+    physical: dict[str, object] = {"artifactLocation": {"uri": quote(location.path, safe="/")}}
+    region = _sarif_region(location)
+    if region:
+        physical["region"] = region
+    return physical
+
+
+def _sarif_region(location: Location) -> dict[str, int]:
+    if location.region is not None:
+        return {
+            "startLine": location.region.start.line + 1,
+            "startColumn": location.region.start.character + 1,
+            "endLine": location.region.end.line + 1,
+            "endColumn": location.region.end.character + 1,
+        }
+    if location.position is not None:
+        return {"startLine": location.position.line + 1, "startColumn": location.position.character + 1}
+    return {}
+
+
+def _sarif_rule_id(diagnostic: Diagnostic) -> str:
+    return f"{diagnostic.source}/{diagnostic.code}"
+
+
+def _sarif_level(severity: Severity) -> str:
+    if severity is Severity.ERROR:
+        return "error"
+    if severity is Severity.WARNING:
+        return "warning"
+    return "note"

sarj_standards/libs/diagnostics/source.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+from array import array
+from bisect import bisect_right
+from dataclasses import dataclass, field
+from pathlib import Path
+import re
+from typing import TYPE_CHECKING, NamedTuple
+
+from .models import Position, Region
+
+
+if TYPE_CHECKING:
+    from typing import Self
+
+
+class _Utf16Index(NamedTuple):
+    starts: array[int]
+    ends: array[int]
+    unit_extras: array[int]
+    byte_extras: array[int]
+
+
+@dataclass(slots=True)
+class SourceDocument:
+    path: Path
+    text: str
+    _lines: tuple[str, ...] = field(init=False, repr=False)
+    _line_byte_offsets: tuple[int, ...] = field(init=False, repr=False)
+    _byte_length: int = field(init=False, repr=False)
+    _utf16_indexes: dict[int, _Utf16Index] = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        lines = tuple(re.findall(r".*?(?:\r\n|\r|\n)|.+\Z", self.text, flags=re.DOTALL)) or ("",)
+        if self.text.endswith(("\n", "\r")):
+            lines = (*lines, "")
+        self._lines = lines
+        offsets: list[int] = []
+        offset = 0
+        for line in self._lines:
+            offsets.append(offset)
+            offset += len(line.encode("utf-8", errors="surrogateescape"))
+        self._line_byte_offsets = tuple(offsets)
+        self._byte_length = offset
+        self._utf16_indexes = {}
+
+    @classmethod
+    def read(cls, path: Path) -> Self:
+        return cls(path, path.read_bytes().decode("utf-8", errors="surrogateescape"))
+
+    def point(self, *, line: int, column: int) -> Position | None:
+        if line < 1 or column < 1 or line > len(self._lines):
+            return None
+        content = self._lines[line - 1].rstrip("\r\n")
+        codepoint_index = column - 1
+        if codepoint_index > len(content):
+            return None
+        prefix = content[:codepoint_index]
+        return Position(
+            line=line - 1,
+            character=len(prefix.encode("utf-16-le", errors="surrogatepass")) // 2,
+            byte_offset=(self._line_byte_offsets[line - 1] + len(prefix.encode("utf-8", errors="surrogateescape"))),
+        )
+
+    def utf16_point(self, *, line: int, character: int) -> Position | None:
+        if line < 0 or character < 0 or line >= len(self._lines):
+            return None
+        content = self._lines[line].rstrip("\r\n")
+        if character == 0:
+            return Position(line=line, character=0, byte_offset=self._line_byte_offsets[line])
+        if content.isascii():
+            if character > len(content):
+                return None
+            return Position(
+                line=line,
+                character=character,
+                byte_offset=self._line_byte_offsets[line] + character,
+            )
+        index = self._utf16_indexes.get(line)
+        if index is None:
+            index = self._build_utf16_index(content)
+            self._utf16_indexes[line] = index
+        starts, ends, unit_extras, byte_extras = index
+        event_index = bisect_right(ends, character)
+        if event_index < len(starts) and starts[event_index] < character < ends[event_index]:
+            return None
+        unit_extra = unit_extras[event_index - 1] if event_index else 0
+        byte_extra = byte_extras[event_index - 1] if event_index else 0
+        codepoint_index = character - unit_extra
+        if codepoint_index < 0 or codepoint_index > len(content):
+            return None
+        return Position(
+            line=line,
+            character=character,
+            byte_offset=self._line_byte_offsets[line] + codepoint_index + byte_extra,
+        )
+
+    @staticmethod
+    def _build_utf16_index(content: str) -> _Utf16Index:
+        starts = array("I")
+        ends = array("I")
+        unit_extras = array("I")
+        byte_extras = array("I")
+        utf16_offset = 0
+        byte_offset = 0
+        for codepoint_index, value in enumerate(content):
+            units = len(value.encode("utf-16-le", errors="surrogatepass")) // 2
+            byte_length = len(value.encode("utf-8", errors="surrogateescape"))
+            if units != 1 or byte_length != 1:
+                end = utf16_offset + units
+                starts.append(utf16_offset)
+                ends.append(end)
+                unit_extras.append(end - codepoint_index - 1)
+                byte_extras.append(byte_offset + byte_length - codepoint_index - 1)
+            utf16_offset += units
+            byte_offset += byte_length
+        return _Utf16Index(starts, ends, unit_extras, byte_extras)
+
+    def byte_point(self, *, line: int, column: int) -> Position | None:
+        if line < 1 or column < 1 or line > len(self._lines):
+            return None
+        content = self._lines[line - 1].rstrip("\r\n")
+        byte_column = column - 1
+        encoded = content.encode("utf-8", errors="surrogateescape")
+        if byte_column > len(encoded):
+            return None
+        try:
+            prefix = encoded[:byte_column].decode("utf-8", errors="surrogateescape")
+        except ValueError:
+            return None
+        if not content.startswith(prefix):
+            return None
+        return Position(
+            line=line - 1,
+            character=len(prefix.encode("utf-16-le", errors="surrogatepass")) // 2,
+            byte_offset=self._line_byte_offsets[line - 1] + byte_column,
+        )
+
+    def region(self, *, start_byte: int, end_byte: int) -> Region:
+        if start_byte < 0 or end_byte < start_byte or end_byte > self._byte_length:
+            msg = "source byte range is outside the document"
+            raise ValueError(msg)
+        return Region(self._position_at_byte(start_byte), self._position_at_byte(end_byte))
+
+    def _position_at_byte(self, offset: int) -> Position:
+        if offset < 0 or offset > self._byte_length:
+            msg = "source byte offset is outside the document"
+            raise ValueError(msg)
+        line = bisect_right(self._line_byte_offsets, offset) - 1
+        line_start = self._line_byte_offsets[line]
+        relative = offset - line_start
+        source_line = self._lines[line]
+        encoded_line = source_line.encode("utf-8", errors="surrogateescape")
+        if relative > 0 and relative < len(encoded_line) and encoded_line[relative - 1 : relative + 1] == b"\r\n":
+            msg = "source byte offset splits a CRLF line terminator"
+            raise ValueError(msg)
+        prefix = encoded_line[:relative]
+        try:
+            decoded = prefix.decode("utf-8", errors="surrogateescape")
+        except UnicodeDecodeError as exc:
+            msg = "source byte offset splits a UTF-8 code point"
+            raise ValueError(msg) from exc
+        if not source_line.startswith(decoded):
+            msg = "source byte offset splits a UTF-8 code point"
+            raise ValueError(msg)
+        local_newlines = decoded.count("\n")
+        current = decoded.rpartition("\n")[2]
+        return Position(
+            line=line + local_newlines,
+            character=len(current.encode("utf-16-le", errors="surrogatepass")) // 2,
+            byte_offset=offset,
+        )

sarj_standards/libs/filesystem.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def is_link_like(path: Path) -> bool:
+    return path.is_symlink() or path.is_junction()