feat: Enhance issue reconciliation by introducing resolutionReason field and improving handling of unanchored issues

Author: rostilos

java-ecosystem/libs/analysis-engine/src/main/java/org/rostilos/codecrow/analysisengine/service/branch/BranchIssueReconciliationService.java

@@ -71,8 +71,7 @@ public BranchIssueReconciliationService(
      * <p>
      * CodeAnalysisIssue records remain immutable historical records.
      */
-    public void reconcileIssueLineNumbers(String rawDiff, Set<String> changedFiles,
-            Branch branch) {
+    public void reconcileIssueLineNumbers(String rawDiff, Set<String> changedFiles, Branch branch) {
         if (rawDiff == null || rawDiff.isBlank())
             return;
 
@@ -480,9 +479,15 @@ public boolean processReconciledIssue(Map<String, Object> issueData, Branch bran
             return false;
 
         boolean resolved = isMarkedResolved(issueData);
-        String resolvedDescription = issueData.get("reason") != null
-                ? String.valueOf(issueData.get("reason"))
+        // Read dedicated resolutionReason field (not 'reason' which is the issue description)
+        String resolvedDescription = issueData.get("resolutionReason") != null
+                ? String.valueOf(issueData.get("resolutionReason"))
                 : null;
+        // Fallback: if AI didn't provide resolutionReason, use 'reason' ONLY if it
+        // differs from the original issue description (i.e. AI actually wrote a fix explanation)
+        if (resolvedDescription == null || resolvedDescription.isBlank()) {
+            resolvedDescription = "Resolved by AI reconciliation";
+        }
 
         if (!resolved)
             return false;
@@ -642,7 +647,8 @@ private void classifyIssuesByContent(List<BranchIssue> fileIssues,
             boolean contentFound = false;
             String updatedLineHash = null;
 
-            // Issues at line <= 1 with no codeSnippet have no reliable anchor
+            // Unanchored issues (line <= 1, no codeSnippet) have no reliable content
+            // anchor → must be reconciled via AI, not deterministic tracking
             boolean hasNoReliableAnchor = (currentLine == null || currentLine <= 1)
                     && (bi.getCodeSnippet() == null || bi.getCodeSnippet().isBlank());
             if (hasNoReliableAnchor) {

java-ecosystem/libs/analysis-engine/src/main/java/org/rostilos/codecrow/analysisengine/service/pr/PrFileEnrichmentService.java

@@ -162,24 +162,46 @@ public PrEnrichmentDataDto enrichPrFiles(
     }
 
     /**
-     * Filter files to only those with supported extensions for parsing.
+     * Blacklist of binary / non-text file extensions that should be excluded
+     * from enrichment. Everything else is allowed.
      */
-    private List<String> filterSupportedFiles(List<String> files, Map<String, Integer> skipReasons) {
-        Set<String> supportedExtensions = Set.of(
-                ".java", ".py", ".js", ".ts", ".jsx", ".tsx",
-                ".go", ".rs", ".rb", ".php", ".cs", ".cpp", ".c", ".h",
-                ".kt", ".scala", ".swift", ".m", ".mm");
+    private static final Set<String> EXCLUDED_EXTENSIONS = Set.of(
+            // Images
+            ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".svg", ".webp", ".tiff", ".tif",
+            // Fonts
+            ".woff", ".woff2", ".ttf", ".otf", ".eot",
+            // Compiled / bytecode
+            ".class", ".pyc", ".pyo", ".o", ".obj", ".dll", ".so", ".dylib", ".exe",
+            ".war", ".ear", ".nar",
+            // Archives
+            ".jar", ".zip", ".tar", ".gz", ".bz2", ".xz", ".7z", ".rar",
+            // Documents / media
+            ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+            ".mp3", ".mp4", ".avi", ".mov", ".wav", ".flac", ".ogg", ".webm",
+            // Data blobs / certs
+            ".bin", ".dat", ".db", ".sqlite", ".sqlite3",
+            ".p12", ".pfx", ".jks", ".keystore", ".der", ".cer",
+            // Lock files (large, auto-generated, no review value)
+            ".lockb",
+            // Misc binary
+            ".wasm", ".map", ".min.js", ".min.css"
+    );
 
+    /**
+     * Filter out known binary / non-text files. Everything not blacklisted is
+     * allowed through for enrichment and file snapshots.
+     */
+    private List<String> filterSupportedFiles(List<String> files, Map<String, Integer> skipReasons) {
         List<String> supported = new ArrayList<>();
         for (String file : files) {
             String lower = file.toLowerCase();
-            boolean isSupported = supportedExtensions.stream()
+            boolean isExcluded = EXCLUDED_EXTENSIONS.stream()
                     .anyMatch(lower::endsWith);
 
-            if (isSupported) {
-                supported.add(file);
+            if (isExcluded) {
+                skipReasons.merge("binary_or_non_text", 1, Integer::sum);
             } else {
-                skipReasons.merge("unsupported_extension", 1, Integer::sum);
+                supported.add(file);
             }
         }
 

java-ecosystem/libs/analysis-engine/src/main/java/org/rostilos/codecrow/analysisengine/service/pr/PrIssueTrackingService.java

@@ -86,6 +86,8 @@ public TrackingSummary trackPrIteration(
         int matched = 0;
         int newOnly = 0;
         int resolved = 0;
+        int unanchoredResolved = 0;
+        int unanchoredPersisting = 0;
 
         for (String filePath : allFiles) {
             List<CodeAnalysisIssue> fileNewIssues = newByFile.getOrDefault(filePath, List.of());
@@ -102,14 +104,118 @@ public TrackingSummary trackPrIteration(
                 continue;
             }
 
+            // ── Separate unanchored previous issues (line <= 1, no lineHash, no codeSnippet) ──
+            // These cannot be reliably tracked by content hashing. Instead, match them
+            // by the original issue ID that the AI preserves in its response.
+            // If the AI omitted the issue entirely → resolved (AI didn't find it).
+            // If the AI re-reported it with isResolved=true → resolved.
+            // If the AI re-reported it with isResolved=false → mark for AI reconciliation.
+            List<CodeAnalysisIssue> anchoredPrevIssues = new ArrayList<>();
+            List<CodeAnalysisIssue> unanchoredPrevIssues = new ArrayList<>();
+            for (CodeAnalysisIssue prev : filePrevIssues) {
+                if (isUnanchored(prev)) {
+                    unanchoredPrevIssues.add(prev);
+                } else {
+                    anchoredPrevIssues.add(prev);
+                }
+            }
+
+            // Handle unanchored previous issues via fingerprint matching.
+            // Unlike IssueTracker (which would make these "immortal" via Pass 3/4),
+            // we match by fingerprint but ALSO respect the new issue's isResolved flag
+            // from the AI's Stage 1 review.
+            if (!unanchoredPrevIssues.isEmpty()) {
+                // Build a lookup: fingerprint → list of new issues with that fingerprint
+                Map<String, List<CodeAnalysisIssue>> newByFingerprint = new LinkedHashMap<>();
+                for (CodeAnalysisIssue newIssue : fileNewIssues) {
+                    String fp = newIssue.getIssueFingerprint();
+                    if (fp != null) {
+                        newByFingerprint.computeIfAbsent(fp, k -> new ArrayList<>()).add(newIssue);
+                    }
+                }
+
+                Set<CodeAnalysisIssue> unanchoredMatchedNewIssues = new HashSet<>();
+                for (CodeAnalysisIssue prevIssue : unanchoredPrevIssues) {
+                    String prevFp = prevIssue.getIssueFingerprint();
+                    List<CodeAnalysisIssue> candidates = prevFp != null
+                            ? newByFingerprint.getOrDefault(prevFp, List.of())
+                            : List.of();
+
+                    // Pick the first unmatched candidate (unanchored issues at line 1 are
+                    // identical in terms of fingerprint, so order doesn't matter)
+                    CodeAnalysisIssue matchedNew = null;
+                    for (CodeAnalysisIssue c : candidates) {
+                        if (!unanchoredMatchedNewIssues.contains(c)) {
+                            matchedNew = c;
+                            break;
+                        }
+                    }
+
+                    if (matchedNew != null) {
+                        // AI re-reported this issue — link them
+                        matchedNew.setTrackedFromIssueId(prevIssue.getId());
+                        matchedNew.setTrackingConfidence("UNANCHORED_FP_MATCH");
+                        unanchoredMatchedNewIssues.add(matchedNew);
+
+                        if (matchedNew.isResolved()) {
+                            // AI marked it resolved in Stage 1 → trust it
+                            unanchoredResolved++;
+                            log.info("Unanchored issue {} resolved by AI (new issue {}, file={})",
+                                    prevIssue.getId(), matchedNew.getId(), filePath);
+                        } else if (prevIssue.isResolved()) {
+                            // Previous was resolved (user dismissed) → carry forward
+                            matchedNew.setResolved(true);
+                            matchedNew.setResolvedDescription(prevIssue.getResolvedDescription());
+                            matchedNew.setResolvedByPr(prevIssue.getResolvedByPr());
+                            matchedNew.setResolvedCommitHash(prevIssue.getResolvedCommitHash());
+                            matchedNew.setResolvedAnalysisId(prevIssue.getResolvedAnalysisId());
+                            matchedNew.setResolvedAt(prevIssue.getResolvedAt());
+                            matchedNew.setResolvedBy(prevIssue.getResolvedBy());
+                            unanchoredResolved++;
+                        } else {
+                            // AI says still present — persists (but can be overridden by
+                            // dedicated AI reconciliation if caller implements it)
+                            unanchoredPersisting++;
+                        }
+                        issueRepository.save(matchedNew);
+                        matched++;
+                    } else {
+                        // AI did NOT re-report this issue → it's resolved
+                        unanchoredResolved++;
+                        resolved++;
+                        log.info("Unanchored issue {} resolved — AI omitted it in new review (file={})",
+                                prevIssue.getId(), filePath);
+                    }
+                }
+
+                // Remove unanchored-matched new issues from the pool before IssueTracker
+                // so they don't get double-counted or double-matched
+                fileNewIssues = fileNewIssues.stream()
+                        .filter(ni -> !unanchoredMatchedNewIssues.contains(ni))
+                        .collect(Collectors.toList());
+            }
+
+            // ── Run IssueTracker on anchored issues only ──
+            if (anchoredPrevIssues.isEmpty() && fileNewIssues.isEmpty()) {
+                continue;
+            }
+            if (anchoredPrevIssues.isEmpty()) {
+                newOnly += fileNewIssues.size();
+                continue;
+            }
+            if (fileNewIssues.isEmpty()) {
+                resolved += anchoredPrevIssues.size();
+                continue;
+            }
+
             // Wrap issues as Trackables
             // RAW = new issues (recomputed against new file content)
             List<TrackableIssue> rawTrackables = fileNewIssues.stream()
                     .map(issue -> recomputeTrackable(issue, newFileContents))
                     .collect(Collectors.toList());
 
             // BASE = previous issues (with original detection-time hashes)
-            List<TrackableIssue> baseTrackables = filePrevIssues.stream()
+            List<TrackableIssue> baseTrackables = anchoredPrevIssues.stream()
                     .map(TrackableIssue::fromOriginal)
                     .collect(Collectors.toList());
 
@@ -125,9 +231,12 @@ public TrackingSummary trackPrIteration(
                 newIssue.setTrackedFromIssueId(prevIssue.getId());
                 newIssue.setTrackingConfidence(pair.confidence().name());
 
-                // If the previous issue was resolved (e.g. user dismissed it), carry that
-                // status forward so the same issue doesn't reappear as an annotation.
+                // Check resolved status from BOTH directions:
+                // 1. Previous issue was resolved (user dismissed, or previous reconciliation)
+                // 2. New issue was marked resolved by the AI in Stage 1 review
+                //    (createIssueFromData sets isResolved=true when AI says isResolved: true)
                 if (prevIssue.isResolved()) {
+                    // Carry forward previous resolution
                     newIssue.setResolved(true);
                     newIssue.setResolvedDescription(prevIssue.getResolvedDescription());
                     newIssue.setResolvedByPr(prevIssue.getResolvedByPr());
@@ -137,6 +246,10 @@ public TrackingSummary trackPrIteration(
                     newIssue.setResolvedBy(prevIssue.getResolvedBy());
                     log.info("Carried forward resolved status from issue {} to new issue {} (confidence={})",
                             prevIssue.getId(), newIssue.getId(), pair.confidence().name());
+                } else if (newIssue.isResolved()) {
+                    // AI in Stage 1 marked this re-emitted issue as resolved — trust it
+                    log.info("AI marked matched issue as resolved: prev={} → new={} (confidence={})",
+                            prevIssue.getId(), newIssue.getId(), pair.confidence().name());
                 }
 
                 issueRepository.save(newIssue);
@@ -150,11 +263,14 @@ public TrackingSummary trackPrIteration(
             resolved += tracking.getUnmatchedBases().size();
         }
 
-        log.info("PR tracking for analysis {}: {} matched, {} new, {} resolved (previous analysis={})",
-                newAnalysis.getId(), matched, newOnly, resolved, previousAnalysis.getId());
+        log.info("PR tracking for analysis {}: {} matched, {} new, {} resolved " +
+                        "(unanchored: {} resolved, {} persisting) (previous analysis={})",
+                newAnalysis.getId(), matched, newOnly, resolved,
+                unanchoredResolved, unanchoredPersisting, previousAnalysis.getId());
 
         return new TrackingSummary(matched, resolved, newOnly,
-                prevIssues.stream().filter(CodeAnalysisIssue::isResolved).count());
+                prevIssues.stream().filter(CodeAnalysisIssue::isResolved).count(),
+                unanchoredResolved, unanchoredPersisting);
     }
 
     // ── Trackable adapter ────────────────────────────────────────────────
@@ -217,6 +333,18 @@ private TrackableIssue recomputeTrackable(CodeAnalysisIssue issue, Map<String, S
         );
     }
 
+    /**
+     * An issue is "unanchored" when it has no meaningful code location —
+     * line is absent or 1, no line hash, and no code snippet.
+     * These cannot be reliably tracked by content hashing (IssueTracker Pass 3/4
+     * would match them forever on fingerprint+line alone).
+     */
+    private boolean isUnanchored(CodeAnalysisIssue issue) {
+        return (issue.getLineNumber() == null || issue.getLineNumber() <= 1)
+                && issue.getLineHash() == null
+                && (issue.getCodeSnippet() == null || issue.getCodeSnippet().isBlank());
+    }
+
     private Map<String, List<CodeAnalysisIssue>> groupByFile(List<CodeAnalysisIssue> issues) {
         return issues.stream()
                 .filter(i -> i.getFilePath() != null)
@@ -232,8 +360,15 @@ public record TrackingSummary(
             int matchedCount,
             int resolvedCount,
             int newIssueCount,
-            long previouslyResolvedCount
+            long previouslyResolvedCount,
+            int unanchoredResolvedCount,
+            int unanchoredPersistingCount
     ) {
+        /** Convenience constructor for first iteration (no tracking). */
+        public TrackingSummary(int matchedCount, int resolvedCount, int newIssueCount, long previouslyResolvedCount) {
+            this(matchedCount, resolvedCount, newIssueCount, previouslyResolvedCount, 0, 0);
+        }
+
         public boolean isFirstIteration() {
             return matchedCount == 0 && resolvedCount == 0 && previouslyResolvedCount == 0;
         }

java-ecosystem/libs/analysis-engine/src/test/java/org/rostilos/codecrow/analysisengine/service/PrFileEnrichmentServiceTest.java

@@ -87,31 +87,38 @@ class DisabledAndEmptyTests {
     @Nested
     @DisplayName("enrichPrFiles() - file filtering")
     class FilterTests {
-        @Test void filtersUnsupportedExtensions() {
+        @Test void filtersBinaryExtensions() {
             PrEnrichmentDataDto result = service.enrichPrFiles(vcsClient, "ws", "repo", "main",
-                    List.of("README.md", "image.png", "data.json", "config.yml"));
+                    List.of("image.png", "photo.jpg", "archive.zip", "lib.dll"));
             assertThat(result.stats().filesSkipped()).isEqualTo(4);
-            assertThat(result.stats().skipReasons()).containsKey("unsupported_extension");
+            assertThat(result.stats().skipReasons()).containsKey("binary_or_non_text");
         }
 
-        @Test void keepsSupportedExtensions() throws Exception {
-            List<String> files = List.of("Main.java", "app.py", "index.ts", "style.css");
+        @Test void keepsAllTextFiles() throws Exception {
+            List<String> files = List.of("Main.java", "app.py", "index.ts", "README.md",
+                    "deploy.sh", "notes.txt", "config.yml", "data.json");
             Map<String, String> contents = Map.of(
                     "Main.java", "public class Main {}",
                     "app.py", "print('hello')",
-                    "index.ts", "export default {}"
+                    "index.ts", "export default {}",
+                    "README.md", "# README",
+                    "deploy.sh", "#!/bin/bash",
+                    "notes.txt", "some notes",
+                    "config.yml", "key: value",
+                    "data.json", "{}"
             );
             when(vcsClient.getFileContents(eq("ws"), eq("repo"), anyList(), eq("main"), anyInt()))
                     .thenReturn(contents);
 
             mockWebServer.enqueue(new MockResponse()
                     .setResponseCode(200)
                     .addHeader("Content-Type", "application/json")
-                    .setBody("{\"results\":[], \"total_files\":3, \"successful\":3, \"failed\":0}"));
+                    .setBody("{\"results\":[], \"total_files\":8, \"successful\":8, \"failed\":0}"));
 
             PrEnrichmentDataDto result = service.enrichPrFiles(vcsClient, "ws", "repo", "main", files);
-            assertThat(result.stats().totalFilesRequested()).isEqualTo(4);
-            assertThat(result.stats().skipReasons()).containsKey("unsupported_extension");
+            assertThat(result.stats().totalFilesRequested()).isEqualTo(8);
+            assertThat(result.stats().filesEnriched()).isEqualTo(8);
+            assertThat(result.stats().skipReasons()).doesNotContainKey("binary_or_non_text");
         }
     }