SONARPY-3844 Create ruling-diff-comment action (#895)

Co-authored-by: Thomas Serre <118730793+thomas-serre-sonarsource@users.noreply.github.com>
GitOrigin-RevId: 45dc70b3e7bfc393134a26919308e5f888ef1569

Author: 2 people

.github/actions/ruling-diff-comment/action.yml

@@ -0,0 +1,38 @@
+name: 'Ruling Diff Comment'
+description: 'Posts a human-readable summary of ruling file changes on PRs'
+
+inputs:
+  pr-number:
+    description: 'Pull request number'
+    required: true
+  repository:
+    description: 'owner/repo'
+    required: true
+  base-sha:
+    description: 'Base commit SHA for diff'
+    required: true
+  head-sha:
+    description: 'Head commit SHA for diff'
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Run unit tests
+      shell: bash
+      run: uv run --project "${{ github.action_path }}" python -m unittest discover -v -s "${{ github.action_path }}" -p "test_ruling_diff.py"
+
+    - name: Generate and post ruling diff comment
+      shell: bash
+      env:
+        GH_TOKEN: ${{ env.GH_TOKEN }}
+        PR_NUMBER: ${{ inputs.pr-number }}
+        REPOSITORY: ${{ inputs.repository }}
+        BASE_SHA: ${{ inputs.base-sha }}
+        HEAD_SHA: ${{ inputs.head-sha }}
+      run: |
+        uv run --project "${{ github.action_path }}" python "${{ github.action_path }}/ruling_diff.py" \
+          --pr-number "$PR_NUMBER" \
+          --repository "$REPOSITORY" \
+          --base-sha "$BASE_SHA" \
+          --head-sha "$HEAD_SHA"

.github/actions/ruling-diff-comment/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "ruling-diff-comment"
+version = "0.1.0"
+description = "GitHub Action helper for ruling diff comments"
+requires-python = ">=3.10"
+dependencies = []
+
+[tool.uv]
+package = false

.github/actions/ruling-diff-comment/ruling_diff.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+
+from ruling_diff_core import build_rule_diffs, format_comment
+from ruling_diff_io import (
+    GitHubActionIO,
+    get_changed_ruling_files,
+    post_or_update_comment,
+)
+
+
+def configure_logging() -> None:
+    level = logging.DEBUG if os.environ.get("RUNNER_DEBUG") else logging.INFO
+    logging.basicConfig(level=level, format="%(asctime)s %(levelname)s %(message)s")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Generate and post ruling diff comment"
+    )
+    parser.add_argument("--pr-number", required=True)
+    parser.add_argument("--repository", required=True)
+    parser.add_argument("--base-sha", required=True)
+    parser.add_argument("--head-sha", required=True)
+    args = parser.parse_args()
+    if "/" not in args.repository:
+        raise ValueError("--repository must be in owner/repo format")
+    return args
+
+
+def has_required_context(args: argparse.Namespace) -> bool:
+    return bool(
+        args.pr_number.strip() and args.base_sha.strip() and args.head_sha.strip()
+    )
+
+
+def main() -> None:
+    configure_logging()
+    args = parse_args()
+    if not has_required_context(args):
+        logging.info("Missing pr/base/head arguments. Skipping ruling diff comment.")
+        return
+
+    changed_files = get_changed_ruling_files(args.base_sha, args.head_sha)
+    if not changed_files:
+        logging.info("No changed ruling json files found. Nothing to do.")
+        return
+
+    logging.info("Found %d changed ruling json files", len(changed_files))
+    io = GitHubActionIO()
+    rule_diffs = build_rule_diffs(
+        changed_files,
+        args.base_sha,
+        args.head_sha,
+        io,
+    )
+    if not rule_diffs:
+        logging.info("Changed files have no issue deltas. No comment will be posted.")
+        return
+
+    comment = format_comment(rule_diffs)
+    post_or_update_comment(args.pr_number, args.repository, comment)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        logging.error("Failed to generate ruling diff comment: %s", exc)
+        sys.exit(1)

.github/actions/ruling-diff-comment/ruling_diff_core.py

@@ -0,0 +1,41 @@
+from ruling_diff_core_lib.comment_rendering import format_comment
+from ruling_diff_core_lib.models_and_constants import (
+    COMMENT_MARKER,
+    COMMENT_SOFT_LIMIT,
+    EXPECTED_RULING_ROOT,
+    IssueDiff,
+    RuleDiff,
+    Snippet,
+)
+from ruling_diff_core_lib.ruling_diff_logic import (
+    build_rule_diffs,
+    diff_ruling_jsons,
+    parse_ruling_path,
+    parse_ruling_relative_path,
+    parse_rule_filename,
+    strip_project_key,
+)
+from ruling_diff_core_lib.snippet_generation import (
+    render_file_level_snippet,
+    render_line_snippet,
+    render_snippet,
+)
+
+__all__ = [
+    "COMMENT_MARKER",
+    "COMMENT_SOFT_LIMIT",
+    "EXPECTED_RULING_ROOT",
+    "IssueDiff",
+    "RuleDiff",
+    "Snippet",
+    "build_rule_diffs",
+    "diff_ruling_jsons",
+    "format_comment",
+    "parse_ruling_path",
+    "parse_ruling_relative_path",
+    "parse_rule_filename",
+    "render_file_level_snippet",
+    "render_line_snippet",
+    "render_snippet",
+    "strip_project_key",
+]

.github/actions/ruling-diff-comment/ruling_diff_core_lib/__init__.py

@@ -0,0 +1,41 @@
+from ruling_diff_core_lib.comment_rendering import format_comment
+from ruling_diff_core_lib.models_and_constants import (
+    COMMENT_MARKER,
+    COMMENT_SOFT_LIMIT,
+    EXPECTED_RULING_ROOT,
+    IssueDiff,
+    RuleDiff,
+    Snippet,
+)
+from ruling_diff_core_lib.ruling_diff_logic import (
+    build_rule_diffs,
+    diff_ruling_jsons,
+    parse_ruling_path,
+    parse_ruling_relative_path,
+    parse_rule_filename,
+    strip_project_key,
+)
+from ruling_diff_core_lib.snippet_generation import (
+    render_file_level_snippet,
+    render_line_snippet,
+    render_snippet,
+)
+
+__all__ = [
+    "COMMENT_MARKER",
+    "COMMENT_SOFT_LIMIT",
+    "EXPECTED_RULING_ROOT",
+    "IssueDiff",
+    "RuleDiff",
+    "Snippet",
+    "build_rule_diffs",
+    "diff_ruling_jsons",
+    "format_comment",
+    "parse_ruling_path",
+    "parse_ruling_relative_path",
+    "parse_rule_filename",
+    "render_file_level_snippet",
+    "render_line_snippet",
+    "render_snippet",
+    "strip_project_key",
+]

.github/actions/ruling-diff-comment/ruling_diff_core_lib/comment_rendering.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from ruling_diff_core_lib.models_and_constants import (
+    COMMENT_MARKER,
+    COMMENT_SOFT_LIMIT,
+    RuleDiff,
+    Snippet,
+)
+
+
+def format_comment(
+    rule_diffs: list[RuleDiff], soft_limit: int = COMMENT_SOFT_LIMIT
+) -> str:
+    if not rule_diffs:
+        return "\n".join(
+            [
+                COMMENT_MARKER,
+                "## Ruling Diff Summary",
+                "",
+                "No issue deltas detected."
+            ]
+        )
+    comment = format_comment_header(rule_diffs)
+    return append_rule_sections_with_soft_limit(comment, rule_diffs, soft_limit)
+
+
+def format_comment_header(rule_diffs: list[RuleDiff]) -> str:
+    added = sum(len(diff.added_lines) for rule in rule_diffs for diff in rule.file_diffs)
+    removed = sum(
+        len(diff.removed_lines) for rule in rule_diffs for diff in rule.file_diffs
+    )
+    return "\n".join(
+        [
+            COMMENT_MARKER,
+            "## Ruling Diff Summary",
+            "",
+            f"Detected changes in {len(rule_diffs)} rule files: {removed} issues removed, {added} issues added.",
+            "",
+        ]
+    )
+
+
+def append_rule_sections_with_soft_limit(
+    comment: str, rule_diffs: list[RuleDiff], soft_limit: int
+) -> str:
+    sections = [format_rule_section(rule_diff) for rule_diff in rule_diffs]
+    accepted_sections: list[str] = []
+    truncated_count = 0
+    for index, section in enumerate(sections):
+        candidate = comment + "\n\n".join(accepted_sections + [section])
+        if len(candidate) > soft_limit:
+            truncated_count = len(sections) - index
+            break
+        accepted_sections.append(section)
+    if accepted_sections:
+        comment += "\n\n".join(accepted_sections)
+    if truncated_count:
+        comment = append_truncation_notice(comment, truncated_count, bool(accepted_sections))
+    return comment
+
+
+def append_truncation_notice(comment: str, count: int, has_sections: bool) -> str:
+    separator = "\n\n" if has_sections else ""
+    return (
+        comment
+        + separator
+        + f"... and {count} more rules with changes (diff too large to display fully)"
+    )
+
+
+def format_rule_section(rule_diff: RuleDiff) -> str:
+    lines = ["<details>", f"<summary>{format_rule_summary(rule_diff)}</summary>", ""]
+    if not rule_diff.snippets:
+        lines.append("No source snippets available for this rule.")
+    else:
+        for snippet in rule_diff.snippets:
+            lines.append(format_snippet_block(snippet))
+            lines.append("")
+    lines.append("</details>")
+    return "\n".join(lines)
+
+
+def format_rule_summary(rule_diff: RuleDiff) -> str:
+    removed = sum(len(diff.removed_lines) for diff in rule_diff.file_diffs)
+    added = sum(len(diff.added_lines) for diff in rule_diff.file_diffs)
+    summary_parts = [
+        f"<b>{rule_diff.rule_key}</b> (<code>{rule_diff.repo}</code>) on <b>{rule_diff.project}</b>",
+        f"{removed} issues removed, {added} issues added",
+    ]
+    if rule_diff.is_new_file:
+        summary_parts.append("new ruling file")
+    if rule_diff.is_deleted_file:
+        summary_parts.append("deleted ruling file")
+    return " - ".join(summary_parts)
+
+
+def format_snippet_block(snippet: Snippet) -> str:
+    return "\n".join([format_snippet_header(snippet), "```python", snippet.body, "```"])
+
+
+def format_snippet_header(snippet: Snippet) -> str:
+    label = "Added" if snippet.change_kind == "added" else "Removed"
+    location = "file-level" if snippet.line_number == 0 else f"line {snippet.line_number}"
+    return f"**{label}** `{snippet.file_path}` ({location})"

.github/actions/ruling-diff-comment/ruling_diff_core_lib/models_and_constants.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+RulingJson = dict[str, list[int]]
+OptionalRulingJson = RulingJson | None
+SourceLines = list[str]
+OptionalSourceLines = SourceLines | None
+SourceCache = dict[tuple[str, str], OptionalSourceLines]
+
+
+class RulingDiffIO(Protocol):
+    def load_json_at_ref(self, path: str, ref: str) -> OptionalRulingJson:
+        ...
+
+    def load_text_at_ref(self, path: str, ref: str) -> str | None:
+        ...
+
+    def resolve_source_path(self, project: str, file_path: str) -> str:
+        ...
+
+EXPECTED_RULING_ROOT = (
+    "private/its-enterprise/ruling/src/test/resources/expected_ruling"
+)
+COMMENT_MARKER = "<!-- ruling-diff-comment -->"
+COMMENT_SOFT_LIMIT = 60000
+SNIPPET_CONTEXT = 5
+MAX_SNIPPETS_PER_FILE = 3
+MAX_SNIPPETS_PER_RULE = 15
+
+PROJECT_SOURCE_OVERRIDES = {
+    "buildbot": "private/its-enterprise/sources_ruling/buildbot-0.8.6p1",
+    "buildbot-slave": "private/its-enterprise/sources_ruling/buildbot-slave-0.8.6p1",
+    "django": "private/its-enterprise/sources_ruling/django-2.2.3",
+    "django-cms": "private/its-enterprise/sources_ruling/django-cms-3.7.1",
+    "docker-compose": "private/its-enterprise/sources_ruling/docker-compose-1.24.1",
+    "mypy": "private/its-enterprise/sources_ruling/mypy-0.782",
+    "numpy": "private/its-enterprise/sources_ruling/numpy-1.16.4",
+    "tornado": "private/its-enterprise/sources_ruling/tornado-2.3",
+    "twisted": "private/its-enterprise/sources_ruling/twisted-12.1.0",
+    "sources_internal_ruling": "private/its-enterprise/sources_internal_ruling",
+    "namespace_basic": "private/its-enterprise/sources_internal_namespace_ruling/basic_namespace",
+    "namespace_mixed": "private/its-enterprise/sources_internal_namespace_ruling/mixed_namespace",
+}
+
+
+@dataclass(frozen=True)
+class IssueDiff:
+    file_path: str
+    added_lines: list[int]
+    removed_lines: list[int]
+
+
+@dataclass(frozen=True)
+class Snippet:
+    file_path: str
+    line_number: int
+    change_kind: str
+    body: str
+
+
+@dataclass(frozen=True)
+class RuleDiff:
+    project: str
+    repo: str
+    rule_key: str
+    file_diffs: list[IssueDiff]
+    snippets: list[Snippet]
+    is_new_file: bool
+    is_deleted_file: bool