Anchor Copilot PR-review suggestion blocks to the correct line(s) (#8806)

## Problem

On [#8772](#8772) two
```suggestion``` blocks were mis-applied, as flagged in review comments:

- **`QltyFileImport` (line 68):** the comment anchored `procedure
GetDialogTitle(): Text` but the fix `exit(ImportFromLbl);` was meant for
line 70. Applying it would overwrite the procedure signature.
- **`QltyImportLogEntry` (line 34):** the comment anchored `{` but the
suggested code was the whole 4-line field. Applying it replaced `{` with
the entire block, duplicating the field instead of just inserting the
`DataClassification` line.

Root cause: the orchestrator always posted a **single-line** comment at
the model's reported `location.line`, but a GitHub suggestion replaces
*exactly* the anchored line(s). When the model anchors a
different/narrower line than the fix targets, the suggestion corrupts
the file.

## Fix

`tools/Code Review/scripts/Invoke-CopilotPRReview.ps1` now validates and
re-anchors each suggestion against the PR-head file content before
posting:

- **Single-line fix** → snapped onto the line it actually rewrites
(whitespace-insensitive match within a small window; trusts the model's
anchor when no unique match exists).
- **Multi-line fix** that edits a construct → posted as a **multi-line
comment** over the full span it replaces, so inserted lines land in
place.
- **Unplaceable fix** → the applicable block is dropped and the change
is shown as a manual, non-applicable snippet.

New helpers: `Get-PrHeadFileLines`, `ConvertTo-LooseLine`,
`Test-OrderedSubsequence`, `Resolve-SuggestionPlacement`;
`New-ReviewComment` gained `start_line`/`start_side` support;
`Build-CommentBody` gained `-SuppressSuggestion`.

## Validation

Unit-tested the resolver against both real cases (snaps to 70..70;
expands to 33..36) plus edge cases (genuine single-line rewrite trusts
anchor, ambiguous match trusts anchor, unplaceable → drop, empty file →
drop). Full script parses cleanly.

Fixes:
[AB#640364](https://dynamicssmb2.visualstudio.com/1fcb79e7-ab07-432a-a3c6-6cf5a88ba4a5/_workitems/edit/640364)

Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

tools/Code Review/README.md

@@ -93,6 +93,16 @@ Every inline finding includes:
   `agent_domain`, `agent_finding`) used by the dedup logic on
   subsequent iterations.
 
+When a finding carries a concrete fix, the orchestrator renders it as a
+GitHub ```suggestion``` block. Because such a block replaces *exactly* the
+line(s) its comment is anchored to, the suggested code is matched against the
+PR-head file to re-derive the correct RIGHT-side span: a single-line fix is
+snapped onto the line it actually rewrites, and a fix that edits a multi-line
+construct is posted as a multi-line comment over the whole span (so an
+inserted property lands in place instead of duplicating the surrounding
+lines). If the fix cannot be anchored with confidence the applicable block is
+dropped and the change is shown as a manual, non-applicable snippet.
+
 ## Per-PR summary comment
 
 Marker: `<!-- copilot-pr-review-summary -->`. Upserted once per

tools/Code Review/scripts/Invoke-CopilotPRReview.ps1

@@ -316,13 +316,23 @@ function Get-ReviewComments { return Get-AllPages "/pulls/$PrNumber/comments" }
 function Get-IssueComments  { return Get-AllPages "/issues/$PrNumber/comments" }
 
 function New-ReviewComment {
-    param([string] $Body, [string] $Path, [int] $Line, [string] $Side)
+    param(
+        [string] $Body, [string] $Path, [int] $Line, [string] $Side,
+        [int] $StartLine = 0, [string] $StartSide = ''
+    )
 
     if (-not $Line -or -not $Side) {
         throw 'Inline review comments require both line and side.'
     }
 
     $payload = @{ body = $Body; commit_id = $PrHeadSha; path = $Path; line = $Line; side = $Side }
+    # Multi-line comment: GitHub anchors the range over [start_line, line] so a
+    # ```suggestion``` block replaces every spanned line in place (a single-line
+    # comment would otherwise replace just $Line, duplicating context).
+    if ($StartLine -gt 0 -and $StartLine -lt $Line) {
+        $payload.start_line = $StartLine
+        $payload.start_side = if ($StartSide) { $StartSide } else { $Side }
+    }
     Invoke-GitHubApi -Method POST -Endpoint "/pulls/$PrNumber/comments" -Body $payload
 }
 
@@ -416,6 +426,139 @@ function Build-LineMap {
     return $map
 }
 
+# ---------------------------------------------------------------------------
+# Suggestion placement (anchor validation for ```suggestion``` blocks)
+#
+# A GitHub suggestion block replaces *exactly* the line(s) its comment is
+# anchored to. The model reports a single semantic `location.line` for a
+# finding, which often is not the line (or full span) the suggested code is
+# meant to replace — e.g. it anchors a procedure declaration while the fix
+# rewrites a statement two lines below, or anchors one line of a multi-line
+# field while the suggestion is the whole field plus an inserted property.
+# Posting such a suggestion verbatim corrupts the file when applied. These
+# helpers re-derive the correct RIGHT-side span by matching the suggested
+# code against the actual PR-head file content, so the block lands in place.
+# ---------------------------------------------------------------------------
+
+# Cache of PR-head file contents (relative path -> string[] lines) so a file is
+# read at most once across all of its findings.
+$script:PrHeadFileCache = @{}
+
+function Get-PrHeadFileLines {
+    param([string] $RelativePath)
+
+    if ($script:PrHeadFileCache.ContainsKey($RelativePath)) {
+        return $script:PrHeadFileCache[$RelativePath]
+    }
+
+    $lines = $null
+    $full = Join-Path $AnalysisWorkspace $RelativePath
+    if (Test-Path -LiteralPath $full) {
+        try {
+            $lines = @(Get-Content -LiteralPath $full -ErrorAction Stop)
+        } catch {
+            Write-Warning "Could not read PR-head file for suggestion placement: $RelativePath ($_)"
+            $lines = $null
+        }
+    }
+
+    $script:PrHeadFileCache[$RelativePath] = $lines
+    return $lines
+}
+
+# Whitespace-insensitive comparison key. Indentation and inter-token spacing
+# frequently differ between the suggested fix and the original line (the fix is
+# often *about* whitespace, e.g. 'exit (X)' -> 'exit(X)'), so boundary/context
+# matching collapses all whitespace to find the line a fix corresponds to.
+function ConvertTo-LooseLine {
+    param([string] $Line)
+    if ($null -eq $Line) { return '' }
+    return ($Line -replace '\s+', '')
+}
+
+# True when every line of $FileSpan appears, in order, somewhere in
+# $Suggestion (loose comparison). This holds when the suggestion is the file
+# span with extra lines inserted (and/or boundary-preserving edits) — the only
+# shape we can safely apply as an in-place multi-line replacement.
+function Test-OrderedSubsequence {
+    param([string[]] $FileSpan, [string[]] $Suggestion)
+
+    $sug = @($Suggestion | ForEach-Object { ConvertTo-LooseLine $_ })
+    $j = 0
+    foreach ($f in $FileSpan) {
+        $fl = ConvertTo-LooseLine $f
+        $found = $false
+        while ($j -lt $sug.Count) {
+            $cur = $sug[$j]; $j++
+            if ($cur -eq $fl) { $found = $true; break }
+        }
+        if (-not $found) { return $false }
+    }
+    return $true
+}
+
+# Resolve the RIGHT-side file span a suggestion should replace.
+# Returns @{ startLine; endLine } (1-based, inclusive) or $null when the
+# suggestion cannot be placed with confidence (caller drops the block).
+function Resolve-SuggestionPlacement {
+    param([string[]] $FileLines, [int] $AnchorLine, [string[]] $SuggestedLines)
+
+    if (-not $FileLines -or $FileLines.Count -eq 0) { return $null }
+    if (-not $SuggestedLines -or $SuggestedLines.Count -eq 0) { return $null }
+
+    $fileCount = $FileLines.Count
+    if ($AnchorLine -lt 1) { $AnchorLine = 1 }
+    if ($AnchorLine -gt $fileCount) { $AnchorLine = $fileCount }
+
+    $sCount    = $SuggestedLines.Count
+    $firstLoose = ConvertTo-LooseLine $SuggestedLines[0]
+    $lastLoose  = ConvertTo-LooseLine $SuggestedLines[$sCount - 1]
+
+    # --- Single-line suggestion: snap to the nearest unique content match. ---
+    if ($sCount -eq 1) {
+        if ((ConvertTo-LooseLine $FileLines[$AnchorLine - 1]) -eq $firstLoose) {
+            return [pscustomobject]@{ startLine = $AnchorLine; endLine = $AnchorLine }
+        }
+        for ($d = 1; $d -le 8; $d++) {
+            $hits = @()
+            foreach ($cand in @(($AnchorLine - $d), ($AnchorLine + $d))) {
+                if ($cand -ge 1 -and $cand -le $fileCount -and
+                    (ConvertTo-LooseLine $FileLines[$cand - 1]) -eq $firstLoose) {
+                    $hits += $cand
+                }
+            }
+            if ($hits.Count -eq 1) { return [pscustomobject]@{ startLine = $hits[0]; endLine = $hits[0] } }
+            if ($hits.Count -gt 1) { break }   # ambiguous at this distance
+        }
+        # No content match found: a one-line replacement of the model's anchor
+        # is still safe (it cannot duplicate context), so trust the anchor.
+        return [pscustomobject]@{ startLine = $AnchorLine; endLine = $AnchorLine }
+    }
+
+    # --- Multi-line suggestion: find an additive span [s,e] near the anchor. ---
+    $best = $null
+    $bestInserted = [int]::MaxValue
+    $lo = [math]::Max(1, $AnchorLine - $sCount - 4)
+    $hi = [math]::Min($fileCount, $AnchorLine + $sCount + 4)
+    for ($s = $lo; $s -le $hi; $s++) {
+        if ((ConvertTo-LooseLine $FileLines[$s - 1]) -ne $firstLoose) { continue }
+        # An additive replacement never spans more lines than the suggestion.
+        $eMax = [math]::Min($fileCount, $s + $sCount - 1)
+        for ($e = $s; $e -le $eMax; $e++) {
+            if ((ConvertTo-LooseLine $FileLines[$e - 1]) -ne $lastLoose) { continue }
+            if ($AnchorLine -lt ($s - 1) -or $AnchorLine -gt ($e + 1)) { continue }
+            $span = @($FileLines[($s - 1)..($e - 1)])
+            if (-not (Test-OrderedSubsequence -FileSpan $span -Suggestion $SuggestedLines)) { continue }
+            $inserted = $sCount - ($e - $s + 1)
+            if ($inserted -lt $bestInserted) {
+                $bestInserted = $inserted
+                $best = [pscustomobject]@{ startLine = $s; endLine = $e }
+            }
+        }
+    }
+    return $best
+}
+
 function Test-GlobMatch {
     param([string] $Filename, [string] $Pattern)
     $f = $Filename -replace '\\', '/'
@@ -1522,7 +1665,7 @@ function Build-ReferenceLink {
 }
 
 function Build-CommentBody {
-    param([object] $Finding)
+    param([object] $Finding, [switch] $SuppressSuggestion)
 
     $domain   = $Finding.domain
     $severity = $Finding.severity
@@ -1567,11 +1710,21 @@ function Build-CommentBody {
         }
     }
 
-    if ($suggested) {
+    if ($suggested -and -not $SuppressSuggestion) {
         $lines.Add('') | Out-Null
         $lines.Add('```suggestion') | Out-Null
         $lines.Add($suggested) | Out-Null
         $lines.Add('```') | Out-Null
+    } elseif ($suggested -and $SuppressSuggestion) {
+        # A concrete fix was identified but its target line(s) could not be
+        # matched against the PR-head file, so an applicable suggestion block
+        # would risk corrupting the file. Surface the intended change as a
+        # non-applicable code snippet instead.
+        $lines.Add('') | Out-Null
+        $lines.Add('**Suggested fix** (apply manually — could not be anchored as a one-click suggestion):') | Out-Null
+        $lines.Add('```al') | Out-Null
+        $lines.Add($suggested) | Out-Null
+        $lines.Add('```') | Out-Null
     }
 
     if ($references.Count -gt 0) {
@@ -1701,6 +1854,46 @@ function Post-Findings {
             $location = $LineMaps[$filePath][$lineNumber]
         }
 
+        # Validate / re-anchor the ```suggestion``` block against the PR-head
+        # file so it replaces the correct line(s). When the finding carries a
+        # suggested fix we re-derive its RIGHT-side span and post the comment
+        # over that span (single- or multi-line). When the fix cannot be placed
+        # confidently we suppress the applicable block (Build-CommentBody falls
+        # back to a manual snippet) and keep the comment at the model's anchor.
+        $suppressSuggestion = $false
+        $commentStartLine = 0
+        $commentStartSide = ''
+        if ($finding.suggestedCode) {
+            $suggested = ([string]$finding.suggestedCode).TrimEnd()
+            $suggLines = [string[]]@($suggested -split "`r?`n")
+            $placement = $null
+            $fileLines = Get-PrHeadFileLines -RelativePath $filePath
+            if ($fileLines -and $suggLines.Count -gt 0) {
+                $placement = Resolve-SuggestionPlacement -FileLines $fileLines -AnchorLine $lineNumber -SuggestedLines $suggLines
+            }
+
+            $placed = $false
+            if ($placement) {
+                $map = if ($LineMaps.ContainsKey($filePath)) { $LineMaps[$filePath] } else { @{} }
+                $spanOk = $true
+                for ($ln = [int]$placement.startLine; $ln -le [int]$placement.endLine; $ln++) {
+                    if (-not ($map.ContainsKey($ln) -and $map[$ln].side -eq 'RIGHT')) { $spanOk = $false; break }
+                }
+                if ($spanOk) {
+                    $location = @{ line = [int]$placement.endLine; side = 'RIGHT' }
+                    if ([int]$placement.startLine -lt [int]$placement.endLine) {
+                        $commentStartLine = [int]$placement.startLine
+                        $commentStartSide = 'RIGHT'
+                    }
+                    $placed = $true
+                }
+            }
+            if (-not $placed) {
+                $suppressSuggestion = $true
+                Write-Host "Suggestion for $($filePath):$lineNumber could not be anchored to the diff; posting as a manual snippet."
+            }
+        }
+
         if ($location) {
             $key = "$($filePath):$($location.line):$($location.side)"
             if ($existingKeys.Contains($key)) {
@@ -1711,11 +1904,11 @@ function Post-Findings {
             }
         }
 
-        $body = Build-CommentBody -Finding $finding
+        $body = Build-CommentBody -Finding $finding -SuppressSuggestion:$suppressSuggestion
 
         try {
             if ($location) {
-                $null = New-ReviewComment -Body $body -Path $filePath -Line $location.line -Side $location.side
+                $null = New-ReviewComment -Body $body -Path $filePath -Line $location.line -Side $location.side -StartLine $commentStartLine -StartSide $commentStartSide
                 $existingKeys.Add("$($filePath):$($location.line):$($location.side)") | Out-Null
                 $existingLocations.Add([pscustomobject]@{ path = $filePath; line = [int]$location.line; side = $location.side }) | Out-Null
                 $postedInline++