Auto-sync comments/diffs

Author: dglsparsons

AGENTS.md

@@ -41,6 +41,12 @@
 - `GET /pulls/{number}/comments` is paginated; `get_review_comments()` must follow `Link` header `rel="next"` (and should request `per_page=100`) or comments silently truncate on larger PRs.
 - LEFT-side old-to-new mappings can legitimately resolve to `0` on full-file deletions; clamp mapped display lines into `[1, line_count]` before extmark placement to avoid out-of-range row errors.
 
+## Learned while implementing autosync triggers
+
+- Save-triggered PR sync should call CLI fetch with `--skip-comments` and preserve in-memory `review.comments`; this refreshes diff/highlights without comment API churn.
+- Auto-sync timers are owned by `init.lua`; `state.clear_review()` should call `neo_reviewer._stop_autosync()` when available to avoid leaking periodic timers across teardown paths and tests.
+- To keep the AI walkthrough panel stable during sync, plumb `keep_ai_ui` through `state.clear_review()` and re-render with `ai_ui.open()` after rebuilding review state.
+
 ## Project Overview
 
 `neo-reviewer` is a Neovim plugin for reviewing GitHub PRs. Hybrid architecture: Rust CLI for GitHub API/diff parsing, Lua plugin for UI.

cli/src/commands/fetch.rs

@@ -6,7 +6,7 @@ use crate::commands::diff::{ensure_git_commit_available, get_pr_review_files};
 use crate::github::client::GitHubClient;
 use crate::github::types::{FetchResponse, PrRef};
 
-pub async fn run(url: &str) -> Result<()> {
+pub async fn run(url: &str, skip_comments: bool) -> Result<()> {
     let client = GitHubClient::new()?;
     let pr_ref = GitHubClient::parse_pr_url(url)?;
 
@@ -20,8 +20,11 @@ pub async fn run(url: &str) -> Result<()> {
     // Fetch change blocks from local git using the PR commit range.
     let files = get_pr_review_files(&pr.base_sha, &pr.head_sha, true)?;
 
-    // Fetch existing comments
-    let comments = client.get_review_comments(&pr_ref).await?;
+    let comments = if skip_comments {
+        Vec::new()
+    } else {
+        client.get_review_comments(&pr_ref).await?
+    };
 
     let response = FetchResponse {
         pr,

cli/src/main.rs

@@ -43,6 +43,10 @@ enum Commands {
         /// GitHub PR URL (e.g., https://github.com/owner/repo/pull/123)
         #[arg(short, long)]
         url: String,
+
+        /// Skip fetching review comments (diff/metadata only)
+        #[arg(long)]
+        skip_comments: bool,
     },
 
     /// Add a review comment to a PR
@@ -167,8 +171,8 @@ async fn main() -> Result<()> {
                 tracked_only,
             })?;
         }
-        Commands::Fetch { url } => {
-            commands::fetch::run(&url).await?;
+        Commands::Fetch { url, skip_comments } => {
+            commands::fetch::run(&url, skip_comments).await?;
         }
         Commands::Comment {
             url,

doc/neo_reviewer.txt

@@ -98,6 +98,13 @@ Call setup() with your options: >lua
                 "Cargo.lock",
             },
         },
+        sync = {
+            on_save = true,              -- Auto-sync after saving reviewed files
+            save_debounce_ms = 400,      -- Debounce save-triggered sync
+            periodic_enabled = true,     -- Periodic background sync
+            periodic_interval_ms = 120000, -- 2 minutes
+            cooldown_ms = 1500,          -- Min spacing between sync starts
+        },
         ai = {
             enabled = false,                      -- Run AI analysis by default
             model = "gpt-5.3-codex", -- Model for Codex CLI (default)
@@ -137,6 +144,22 @@ review_diff ~
     - `noise_files`: Basenames to skip when `skip_noise_files` is enabled.
       Any file with a matching basename is excluded from local diff review.
 
+                                                        *neo_reviewer-config-sync*
+sync ~
+    Configure automatic review synchronization.
+    - `on_save`: Trigger sync after saving a file in the active review
+      (default: true). Applies to both PR and local diff reviews.
+    - `save_debounce_ms`: Debounce window for save-triggered sync
+      (default: 400).
+    - `periodic_enabled`: Enable periodic background sync
+      (default: true).
+    - `periodic_interval_ms`: Periodic sync interval in milliseconds
+      (default: 120000 / 2 minutes).
+    - `cooldown_ms`: Minimum time between sync starts in milliseconds
+      (default: 1500). This guards against stacked sync runs.
+    Automatic save/periodic sync runs silently on success (no "Synced"
+    notifications). Errors still notify.
+
                                                            *neo_reviewer-config-ai*
 ai ~
     Configure AI-powered review analysis. Requires an AI CLI (Codex CLI by
@@ -268,6 +291,10 @@ These user commands are created when you call `setup()`.
       same target/selector options used by |:ReviewDiff| and reapplies markers.
     Preserves cursor position, expanded change block state, and AI summary when
     possible.
+    By default, sync also runs automatically on save for reviewed files and as
+    a periodic background refresh every 2 minutes. Save-triggered PR sync skips
+    comment refresh (diff/highlights only). Automatic sync keeps the AI
+    walkthrough window open if it is already open. Configure via `sync.*`.
 
 ==============================================================================
 6. FUNCTIONS                                            *neo_reviewer-functions*
@@ -411,6 +438,9 @@ require("neo_reviewer").sync()                                   *neo_reviewer.s
     - During local diff review: re-runs local diff sourcing with the same
       selection options used by |neo_reviewer.review_diff()|.
     Preserves cursor position and expanded change block state when possible.
+    Manual sync (`:ReviewSync`) always refreshes comments for PR reviews.
+    Automatic save-triggered sync refreshes diff/highlights but skips comment
+    refresh for PR reviews.
     See |:ReviewSync|.
 
 require("neo_reviewer").toggle_ai_feedback()     *neo_reviewer.toggle_ai_feedback()*

lua/neo_reviewer/cli.lua

@@ -37,6 +37,9 @@ local config = require("neo_reviewer.config")
 ---@field merge_base? boolean Compare against merge-base(HEAD, target)
 ---@field tracked_only? boolean Exclude untracked files
 
+---@class NRFetchPROpts
+---@field skip_comments? boolean Skip fetching review comments
+
 ---@class NRCLIModule
 local M = {}
 
@@ -169,10 +172,17 @@ end
 
 ---@param url string
 ---@param callback fun(data: NRReviewData?, err: string?)
-function M.fetch_pr(url, callback)
+---@param opts? NRFetchPROpts
+function M.fetch_pr(url, callback, opts)
+    opts = opts or {}
+    local args = { "fetch", "--url", url }
+    if opts.skip_comments then
+        table.insert(args, "--skip-comments")
+    end
+
     Job:new({
         command = config.values.cli_path,
-        args = { "fetch", "--url", url },
+        args = args,
         on_exit = vim.schedule_wrap(function(j, code)
             if code == 0 then
                 local output = table.concat(j:result(), "\n")

lua/neo_reviewer/config.lua

@@ -36,6 +36,13 @@
 ---@field skip_noise_files boolean Whether to skip common lock/noise files in local diff reviews
 ---@field noise_files string[] Basenames to skip in local diff reviews when skip_noise_files is enabled
 
+---@class NRSync
+---@field on_save boolean Whether to trigger sync after saving a reviewed file
+---@field save_debounce_ms integer Debounce window for save-triggered sync
+---@field periodic_enabled boolean Whether to run periodic background sync
+---@field periodic_interval_ms integer Periodic sync interval in milliseconds
+---@field cooldown_ms integer Minimum time between sync starts in milliseconds
+
 ---@class NRConfig
 ---@field cli_path string Path to the neo-reviewer CLI binary
 ---@field signs NRSigns
@@ -44,6 +51,7 @@
 ---@field thread_window NRThreadWindow
 ---@field input_window NRInputWindow
 ---@field review_diff NRReviewDiff
+---@field sync NRSync
 ---@field ai NRAI AI analysis configuration
 
 ---@class NRPartialSigns
@@ -77,6 +85,13 @@
 ---@field skip_noise_files? boolean Whether to skip common lock/noise files in local diff reviews
 ---@field noise_files? string[] Basenames to skip in local diff reviews when skip_noise_files is enabled
 
+---@class NRPartialSync
+---@field on_save? boolean Whether to trigger sync after saving a reviewed file
+---@field save_debounce_ms? integer Debounce window for save-triggered sync
+---@field periodic_enabled? boolean Whether to run periodic background sync
+---@field periodic_interval_ms? integer Periodic sync interval in milliseconds
+---@field cooldown_ms? integer Minimum time between sync starts in milliseconds
+
 ---@class NRPartialAI
 ---@field enabled? boolean Whether AI analysis is enabled by default
 ---@field model? string Model for AI CLI
@@ -92,6 +107,7 @@
 ---@field thread_window? NRPartialThreadWindow
 ---@field input_window? NRPartialInputWindow
 ---@field review_diff? NRPartialReviewDiff
+---@field sync? NRPartialSync
 ---@field ai? NRPartialAI AI analysis configuration
 
 ---@class NRConfigModule
@@ -160,6 +176,13 @@ M.values = {
             ".terraform.lock.hcl",
         },
     },
+    sync = {
+        on_save = true,
+        save_debounce_ms = 400,
+        periodic_enabled = true,
+        periodic_interval_ms = 120000,
+        cooldown_ms = 1500,
+    },
     ai = {
         enabled = false,
         model = "gpt-5.3-codex",