iam-policy-validator 1.10.2__py3-none-any.whl → 1.11.0__py3-none-any.whl

iam_validator/core/pr_commenter.py

@@ -13,6 +13,7 @@ from iam_validator.core.constants import (
     REVIEW_IDENTIFIER,
     SUMMARY_IDENTIFIER,
 )
+from iam_validator.core.diff_parser import DiffParser
 from iam_validator.core.label_manager import LabelManager
 from iam_validator.core.models import ValidationIssue, ValidationReport
 from iam_validator.core.report import ReportGenerator
@@ -21,6 +22,34 @@ from iam_validator.integrations.github_integration import GitHubIntegration, Rev
 logger = logging.getLogger(__name__)
 
 
+class ContextIssue:
+    """Represents an issue in a modified statement but on an unchanged line.
+
+    These issues are shown in the summary comment rather than as inline comments,
+    since GitHub only allows comments on lines that appear in the PR diff.
+    """
+
+    def __init__(
+        self,
+        file_path: str,
+        statement_index: int,
+        line_number: int,
+        issue: ValidationIssue,
+    ):
+        """Initialize context issue.
+
+        Args:
+            file_path: Relative path to the file
+            statement_index: Zero-based statement index
+            line_number: Line number where the issue exists
+            issue: The validation issue
+        """
+        self.file_path = file_path
+        self.statement_index = statement_index
+        self.line_number = line_number
+        self.issue = issue
+
+
 class PRCommenter:
     """Posts validation findings as PR comments."""
 
@@ -41,6 +70,7 @@ class PRCommenter:
         Args:
             github: GitHubIntegration instance (will create one if None)
             cleanup_old_comments: Whether to clean up old bot comments before posting new ones
+                                 (kept for backward compatibility but now handled automatically)
             fail_on_severities: List of severity levels that should trigger REQUEST_CHANGES
                                (e.g., ["error", "critical", "high"])
             severity_labels: Mapping of severity levels to label name(s) for automatic label management
@@ -54,6 +84,8 @@ class PRCommenter:
         self.cleanup_old_comments = cleanup_old_comments
         self.fail_on_severities = fail_on_severities or ["error", "critical"]
         self.severity_labels = severity_labels or {}
+        # Track issues in modified statements that are on unchanged lines
+        self._context_issues: list[ContextIssue] = []
 
     async def post_findings_to_pr(
         self,
@@ -86,10 +118,15 @@ class PRCommenter:
 
         success = True
 
-        # Clean up old bot comments if enabled
-        if self.cleanup_old_comments and create_review:
-            logger.info("Cleaning up old review comments from previous runs...")
-            await self.github.cleanup_bot_review_comments(self.REVIEW_IDENTIFIER)
+        # Note: Cleanup is now handled smartly by update_or_create_review_comments()
+        # It will update existing comments, create new ones, and delete resolved ones
+
+        # Post line-specific review comments FIRST
+        # (This populates self._context_issues)
+        if create_review:
+            if not await self._post_review_comments(report):
+                logger.error("Failed to post review comments")
+                success = False
 
         # Post summary comment (potentially as multiple parts)
         if add_summary_comment:
@@ -108,12 +145,6 @@ class PRCommenter:
                 else:
                     logger.info("Posted summary comment")
 
-        # Post line-specific review comments
-        if create_review:
-            if not await self._post_review_comments(report):
-                logger.error("Failed to post review comments")
-                success = False
-
         # Manage PR labels based on severity findings
         if manage_labels and self.severity_labels:
             label_manager = LabelManager(self.github, self.severity_labels)
@@ -129,7 +160,11 @@ class PRCommenter:
         return success
 
     async def _post_review_comments(self, report: ValidationReport) -> bool:
-        """Post line-specific review comments.
+        """Post line-specific review comments with strict diff filtering.
+
+        Only posts comments on lines that were actually changed in the PR.
+        Issues in modified statements but on unchanged lines are tracked in
+        self._context_issues for inclusion in the summary comment.
 
         Args:
             report: Validation report
@@ -140,8 +175,25 @@ class PRCommenter:
         if not self.github:
             return False
 
+        # Clear context issues from previous runs
+        self._context_issues = []
+
+        # Fetch PR diff information
+        logger.info("Fetching PR diff information for strict filtering...")
+        pr_files = await self.github.get_pr_files()
+        if not pr_files:
+            logger.warning(
+                "Could not fetch PR diff information. "
+                "Falling back to unfiltered commenting (may fail if lines not in diff)."
+            )
+            parsed_diffs = {}
+        else:
+            parsed_diffs = DiffParser.parse_pr_files(pr_files)
+            logger.info(f"Parsed diffs for {len(parsed_diffs)} file(s)")
+
         # Group issues by file
-        comments_by_file: dict[str, list[dict[str, Any]]] = {}
+        inline_comments: list[dict[str, Any]] = []
+        context_issue_count = 0
 
         for result in report.results:
             if not result.issues:
@@ -155,75 +207,149 @@ class PRCommenter:
                 )
                 continue
 
-            # Try to determine line numbers from the policy file
+            # Get diff info for this file
+            diff_info = parsed_diffs.get(relative_path)
+            if not diff_info:
+                logger.debug(
+                    f"{relative_path} not in PR diff or no changes, skipping inline comments"
+                )
+                # Still process issues for summary
+                for issue in result.issues:
+                    if issue.statement_index is not None:
+                        line_num = self._find_issue_line(
+                            issue, result.policy_file, self._get_line_mapping(result.policy_file)
+                        )
+                        if line_num:
+                            self._context_issues.append(
+                                ContextIssue(relative_path, issue.statement_index, line_num, issue)
+                            )
+                            context_issue_count += 1
+                continue
+
+            # Get line mapping and modified statements for this file
             line_mapping = self._get_line_mapping(result.policy_file)
+            modified_statements = DiffParser.get_modified_statements(
+                line_mapping, diff_info.changed_lines, result.policy_file
+            )
 
+            logger.debug(
+                f"{relative_path}: {len(diff_info.changed_lines)} changed lines, "
+                f"{len(modified_statements)} modified statements"
+            )
+
+            # Process each issue with strict filtering
             for issue in result.issues:
-                # Determine the line number for this issue
                 line_number = self._find_issue_line(issue, result.policy_file, line_mapping)
 
-                if line_number:
-                    comment = {
-                        "path": relative_path,  # Use relative path for GitHub
-                        "line": line_number,
-                        "body": issue.to_pr_comment(),
-                    }
+                if not line_number:
+                    logger.debug(
+                        f"Could not determine line number for issue in {relative_path}: {issue.issue_type}"
+                    )
+                    continue
 
-                    if relative_path not in comments_by_file:
-                        comments_by_file[relative_path] = []
-                    comments_by_file[relative_path].append(comment)
+                # SPECIAL CASE: Policy-level issues (privilege escalation, etc.)
+                # Post to first available line in diff, preferring line 1 if available
+                if issue.statement_index == -1:
+                    # Try to find the best line to post the comment
+                    comment_line = None
+
+                    if line_number in diff_info.changed_lines:
+                        # Best case: line 1 is in the diff
+                        comment_line = line_number
+                    elif diff_info.changed_lines:
+                        # Fallback: use the first changed line in the file
+                        # This ensures policy-level issues always appear as inline comments
+                        comment_line = min(diff_info.changed_lines)
+                        logger.debug(
+                            f"Policy-level issue at line {line_number}, posting to first changed line {comment_line}"
+                        )
+
+                    if comment_line:
+                        # Post as inline comment at the determined line
+                        inline_comments.append(
+                            {
+                                "path": relative_path,
+                                "line": comment_line,
+                                "body": issue.to_pr_comment(),
+                            }
+                        )
+                        logger.debug(
+                            f"Policy-level inline comment: {relative_path}:{comment_line} - {issue.issue_type}"
+                        )
+                    else:
+                        # No changed lines in file - add to summary comment
+                        self._context_issues.append(
+                            ContextIssue(relative_path, issue.statement_index, line_number, issue)
+                        )
+                        context_issue_count += 1
+                        logger.debug(
+                            f"Policy-level issue (no diff lines): {relative_path} - {issue.issue_type}"
+                        )
+                # STRICT FILTERING: Only comment if line is in the diff
+                elif line_number in diff_info.changed_lines:
+                    # Exact match - post inline comment
+                    inline_comments.append(
+                        {
+                            "path": relative_path,
+                            "line": line_number,
+                            "body": issue.to_pr_comment(),
+                        }
+                    )
+                    logger.debug(
+                        f"Inline comment: {relative_path}:{line_number} - {issue.issue_type}"
+                    )
+                elif issue.statement_index in modified_statements:
+                    # Issue in modified statement but on unchanged line - save for summary
+                    self._context_issues.append(
+                        ContextIssue(relative_path, issue.statement_index, line_number, issue)
+                    )
+                    context_issue_count += 1
                     logger.debug(
-                        f"Prepared review comment for {relative_path}:{line_number} - {issue.issue_type}"
+                        f"Context issue: {relative_path}:{line_number} (statement {issue.statement_index} modified) - {issue.issue_type}"
                     )
                 else:
+                    # Issue in completely unchanged statement - ignore for inline and summary
                     logger.debug(
-                        f"Could not determine line number for issue in {relative_path}: {issue.issue_type}"
+                        f"Skipped issue in unchanged statement: {relative_path}:{line_number} - {issue.issue_type}"
                     )
 
-        # If no line-specific comments, skip
-        if not comments_by_file:
-            logger.info("No line-specific comments to post")
-            return True
-
-        # Flatten comments list
-        all_comments = []
-        for file_comments in comments_by_file.values():
-            all_comments.extend(file_comments)
-
+        # Log filtering results
         logger.info(
-            f"Posting {len(all_comments)} review comments across {len(comments_by_file)} file(s)"
+            f"Diff filtering results: {len(inline_comments)} inline comments, "
+            f"{context_issue_count} context issues for summary"
         )
 
-        # Log files that will receive comments (for debugging)
-        for file_path, file_comments in comments_by_file.items():
-            logger.debug(f"  {file_path}: {len(file_comments)} comment(s)")
+        # If no inline comments, skip review creation but still return success
+        if not inline_comments:
+            logger.info("No inline comments to post (after diff filtering)")
+            return True
 
         # Determine review event based on fail_on_severities config
-        # Check if any issue has a severity that should trigger REQUEST_CHANGES
         has_blocking_issues = any(
             issue.severity in self.fail_on_severities
             for result in report.results
             for issue in result.issues
         )
 
-        # Set review event: request changes if any blocking issues, else comment
         event = ReviewEvent.REQUEST_CHANGES if has_blocking_issues else ReviewEvent.COMMENT
-        logger.info(f"Creating PR review with event: {event.value}")
+        logger.info(
+            f"Creating PR review with {len(inline_comments)} comments, event: {event.value}"
+        )
 
-        # Post review with comments (use minimal body since summary comment has the details)
-        # Only include the identifier for cleanup purposes
+        # Post review with smart update-or-create logic
         review_body = f"{self.REVIEW_IDENTIFIER}"
 
-        success = await self.github.create_review_with_comments(
-            comments=all_comments,
+        success = await self.github.update_or_create_review_comments(
+            comments=inline_comments,
             body=review_body,
             event=event,
+            identifier=self.REVIEW_IDENTIFIER,
         )
 
         if success:
-            logger.info(f"Successfully created PR review with {len(all_comments)} comments")
+            logger.info("Successfully managed PR review comments (update/create/delete)")
         else:
-            logger.error("Failed to create PR review")
+            logger.error("Failed to manage PR review comments")
 
         return success
 
@@ -238,8 +364,8 @@ class PRCommenter:
         Returns:
             Relative path from repository root, or None if cannot be determined
         """
-        import os
-        from pathlib import Path
+        import os  # pylint: disable=import-outside-toplevel
+        from pathlib import Path  # pylint: disable=import-outside-toplevel
 
         # If already relative, use as-is
         if not os.path.isabs(policy_file):
@@ -421,7 +547,9 @@ async def post_report_to_pr(
         report = ValidationReport.model_validate(report_data)
 
         # Load config to get fail_on_severity and severity_labels settings
-        from iam_validator.core.config.config_loader import ConfigLoader
+        from iam_validator.core.config.config_loader import (  # pylint: disable=import-outside-toplevel
+            ConfigLoader,
+        )
 
         config = ConfigLoader.load_config(config_path)
         fail_on_severities = config.get_setting("fail_on_severity", ["error", "critical"])

iam_validator/core/report.py

@@ -819,24 +819,26 @@ class ReportGenerator:
             issue: The validation issue to format
             policy_file: Optional policy file path (currently unused, kept for compatibility)
         """
-        # Use 1-indexed statement numbers for user-facing output
-        statement_num = issue.statement_index + 1
-
-        # Build statement location reference
-        # Note: We show plain text here instead of links because:
-        # 1. GitHub's diff anchor format only works for files in the PR diff
-        # 2. Inline review comments (posted separately) already provide perfect navigation
-        # 3. Summary comment is for overview, not detailed navigation
-        if issue.line_number:
-            location = f"Statement {statement_num} (Line {issue.line_number})"
-            if issue.statement_sid:
-                location = (
-                    f"`{issue.statement_sid}` (statement {statement_num}, line {issue.line_number})"
-                )
+        # Handle policy-level issues (statement_index = -1)
+        if issue.statement_index == -1:
+            location = "Policy-level"
         else:
-            location = f"Statement {statement_num}"
-            if issue.statement_sid:
-                location = f"`{issue.statement_sid}` (statement {statement_num})"
+            # Use 1-indexed statement numbers for user-facing output
+            statement_num = issue.statement_index + 1
+
+            # Build statement location reference
+            # Note: We show plain text here instead of links because:
+            # 1. GitHub's diff anchor format only works for files in the PR diff
+            # 2. Inline review comments (posted separately) already provide perfect navigation
+            # 3. Summary comment is for overview, not detailed navigation
+            if issue.line_number:
+                location = f"Statement {statement_num} (Line {issue.line_number})"
+                if issue.statement_sid:
+                    location = f"`{issue.statement_sid}` (statement {statement_num}, line {issue.line_number})"
+            else:
+                location = f"Statement {statement_num}"
+                if issue.statement_sid:
+                    location = f"`{issue.statement_sid}` (statement {statement_num})"
 
         parts = []
 

iam_validator/integrations/github_integration.py

@@ -291,7 +291,7 @@ class GitHubIntegration:
         except httpx.HTTPStatusError as e:
             logger.error(f"HTTP error: {e.response.status_code} - {e.response.text}")
             return None
-        except Exception as e:
+        except Exception as e:  # pylint: disable=broad-exception-caught
             logger.error(f"Request failed: {e}")
             return None
 
@@ -486,6 +486,57 @@ class GitHubIntegration:
             return result
         return []
 
+    async def get_bot_review_comments_with_location(
+        self, identifier: str = constants.BOT_IDENTIFIER
+    ) -> dict[tuple[str, int, str], dict[str, Any]]:
+        """Get bot review comments indexed by file path, line number, and issue type.
+
+        This enables efficient lookup to update existing comments.
+        Uses (path, line, issue_type) as key to support multiple issues at the same line.
+
+        Args:
+            identifier: String to identify bot comments
+
+        Returns:
+            Dict mapping (file_path, line_number, issue_type) to comment metadata dict
+            Comment dict contains: id, body, path, line, issue_type, commit_id
+        """
+        comments = await self.get_review_comments()
+        bot_comments_map: dict[tuple[str, int, str], dict[str, Any]] = {}
+
+        for comment in comments:
+            if not isinstance(comment, dict):
+                continue
+
+            body = comment.get("body", "")
+            comment_id = comment.get("id")
+            path = comment.get("path")
+            line = comment.get("line") or comment.get("original_line")
+
+            # Check if this is a bot comment with valid location
+            if (
+                identifier in str(body)
+                and isinstance(comment_id, int)
+                and isinstance(path, str)
+                and isinstance(line, int)
+            ):
+                # Extract issue type from HTML comment
+                issue_type_match = re.search(r"<!-- issue-type: (\w+) -->", body)
+                issue_type = issue_type_match.group(1) if issue_type_match else "unknown"
+
+                key = (path, line, issue_type)
+                bot_comments_map[key] = {
+                    "id": comment_id,
+                    "body": body,
+                    "path": path,
+                    "line": line,
+                    "issue_type": issue_type,
+                    "commit_id": comment.get("commit_id"),
+                }
+
+        logger.debug(f"Found {len(bot_comments_map)} bot review comments at specific locations")
+        return bot_comments_map
+
     async def delete_review_comment(self, comment_id: int) -> bool:
         """Delete a specific review comment.
 
@@ -505,6 +556,47 @@ class GitHubIntegration:
             return True
         return False
 
+    async def resolve_review_comment(self, comment_id: int) -> bool:
+        """Resolve a specific review comment.
+
+        Args:
+            comment_id: ID of the comment to resolve
+
+        Returns:
+            True if successful, False otherwise
+        """
+        result = await self._make_request(
+            "PATCH",
+            f"pulls/comments/{comment_id}",
+            json={"state": "resolved"},
+        )
+
+        if result is not None:
+            logger.info(f"Successfully resolved review comment {comment_id}")
+            return True
+        return False
+
+    async def update_review_comment(self, comment_id: int, new_body: str) -> bool:
+        """Update the body text of an existing review comment.
+
+        Args:
+            comment_id: ID of the comment to update
+            new_body: New comment text (markdown supported)
+
+        Returns:
+            True if successful, False otherwise
+        """
+        result = await self._make_request(
+            "PATCH",
+            f"pulls/comments/{comment_id}",
+            json={"body": new_body},
+        )
+
+        if result is not None:
+            logger.debug(f"Successfully updated review comment {comment_id}")
+            return True
+        return False
+
     async def cleanup_bot_review_comments(self, identifier: str = constants.BOT_IDENTIFIER) -> int:
         """Delete all review comments from the bot (from previous runs).
 
@@ -536,6 +628,40 @@ class GitHubIntegration:
 
         return deleted_count
 
+    async def cleanup_bot_review_comments_by_resolving(
+        self, identifier: str = constants.BOT_IDENTIFIER
+    ) -> int:
+        """Resolve all review comments from the bot (from previous runs).
+
+        This marks old/outdated comments as resolved instead of deleting them,
+        preserving them in the PR for audit trail purposes.
+
+        Args:
+            identifier: String to identify bot comments
+
+        Returns:
+            Number of comments resolved
+        """
+        comments = await self.get_review_comments()
+        resolved_count = 0
+
+        for comment in comments:
+            if not isinstance(comment, dict):
+                continue
+
+            body = comment.get("body", "")
+            comment_id = comment.get("id")
+
+            # Check if this is a bot comment
+            if identifier in str(body) and isinstance(comment_id, int):
+                if await self.resolve_review_comment(comment_id):
+                    resolved_count += 1
+
+        if resolved_count > 0:
+            logger.info(f"Resolved {resolved_count} old review comments")
+
+        return resolved_count
+
     async def create_review_comment(
         self,
         commit_id: str,
@@ -646,6 +772,129 @@ class GitHubIntegration:
             return True
         return False
 
+    async def update_or_create_review_comments(
+        self,
+        comments: list[dict[str, Any]],
+        body: str = "",
+        event: ReviewEvent = ReviewEvent.COMMENT,
+        identifier: str = constants.REVIEW_IDENTIFIER,
+    ) -> bool:
+        """Smart comment management: update existing, create new, delete resolved.
+
+        This method implements a three-step process:
+        1. Fetch existing bot comments at each location
+        2. For each new comment: update if exists, create if new
+        3. Delete old comments where issues have been resolved
+
+        Args:
+            comments: List of comment dicts with keys: path, line, body, (optional) side
+            body: The overall review body text
+            event: The review event type (APPROVE, REQUEST_CHANGES, COMMENT)
+            identifier: String to identify bot comments (for matching existing)
+
+        Returns:
+            True if successful, False otherwise
+
+        Example:
+            # First run: Creates 3 comments
+            comments = [
+                {"path": "policy.json", "line": 5, "body": "Issue A"},
+                {"path": "policy.json", "line": 10, "body": "Issue B"},
+                {"path": "policy.json", "line": 15, "body": "Issue C"},
+            ]
+
+            # Second run: Updates Issue A, keeps B, deletes C (resolved), adds D
+            comments = [
+                {"path": "policy.json", "line": 5, "body": "Issue A (updated)"},
+                {"path": "policy.json", "line": 10, "body": "Issue B"},  # Same = no update
+                {"path": "policy.json", "line": 20, "body": "Issue D"},  # New
+            ]
+            # Result: line 15 comment deleted (resolved), line 5 updated, line 20 created
+        """
+        # Step 1: Get existing bot comments mapped by location
+        existing_comments = await self.get_bot_review_comments_with_location(identifier)
+        logger.debug(f"Found {len(existing_comments)} existing bot comments")
+
+        # Track which existing comments we've seen (to know what to delete later)
+        seen_locations: set[tuple[str, int, str]] = set()
+        updated_count = 0
+        created_count = 0
+
+        # Step 2: Update or create each new comment
+        new_comments_for_review: list[dict[str, Any]] = []
+
+        for comment in comments:
+            path = comment["path"]
+            line = comment["line"]
+            new_body = comment["body"]
+
+            # Extract issue type from comment body HTML comment
+            issue_type_match = re.search(r"<!-- issue-type: (\w+) -->", new_body)
+            issue_type = issue_type_match.group(1) if issue_type_match else "unknown"
+
+            location = (path, line, issue_type)
+            seen_locations.add(location)
+
+            existing = existing_comments.get(location)
+
+            if existing:
+                # Comment exists at this location - check if body changed
+                if existing["body"] != new_body:
+                    # Update the existing comment
+                    success = await self.update_review_comment(existing["id"], new_body)
+                    if success:
+                        updated_count += 1
+                        logger.debug(f"Updated comment at {path}:{line}")
+                    else:
+                        logger.warning(f"Failed to update comment at {path}:{line}")
+                else:
+                    # Body unchanged, skip update
+                    logger.debug(f"Comment at {path}:{line} unchanged, skipping update")
+            else:
+                # New comment - collect for batch creation
+                new_comments_for_review.append(comment)
+
+        # Step 3: Create new comments via review API (if any)
+        if new_comments_for_review:
+            success = await self.create_review_with_comments(
+                new_comments_for_review,
+                body=body,
+                event=event,
+            )
+            if success:
+                created_count = len(new_comments_for_review)
+                logger.info(f"Created {created_count} new review comments")
+            else:
+                logger.error("Failed to create new review comments")
+                return False
+
+        # Step 4: Delete comments for resolved issues (not in new comment set)
+        # IMPORTANT: Only delete comments for files that are in the current batch
+        # to avoid deleting comments from other files processed in the same run
+        deleted_count = 0
+        files_in_batch = {comment["path"] for comment in comments}
+
+        for location, existing in existing_comments.items():
+            # Only delete if:
+            # 1. This location is not in the new comment set (resolved issue)
+            # 2. AND this file is in the current batch (don't touch other files' comments)
+            if location not in seen_locations and existing["path"] in files_in_batch:
+                # This comment location is no longer in the new issues - delete it
+                success = await self.delete_review_comment(existing["id"])
+                if success:
+                    deleted_count += 1
+                    logger.debug(
+                        f"Deleted resolved comment at {existing['path']}:{existing['line']}"
+                    )
+
+        # Summary
+        logger.info(
+            f"Review comment management: {updated_count} updated, "
+            f"{created_count} created, {deleted_count} deleted (resolved)"
+        )
+
+        return True
+
     # ==================== PR Labels ====================
 
     async def add_labels(self, labels: list[str]) -> bool: