feat(rust): port stack note to native Rust (#1515)

The Rust binary now serves ``mergify stack note [<commit>]
[-m <msg>] [--append] [--remove]`` natively. The Python
implementation (``mergify_cli/stack/note.py``, its click
registration in ``mergify_cli/stack/cli.py``, and the unit suite
in ``mergify_cli/tests/stack/test_note.py``) is removed in the
same PR.

Second ``stack`` subcommand to land natively (after ``stack new``
in the preceding commit). The hybrid dispatcher in
``crates/mergify-cli/src/main.rs::dispatch_stack`` grows a single
``"note"`` arm; everything else still flows through the Python
shim.

``mergify stack note [<COMMIT>]`` resolves the target commit by:

1. ``None`` → ``HEAD``.
2. Argument matches ``I[0-9a-f]+`` — walk the stack
   (``<merge-base trunk HEAD>..HEAD``) and match by
   ``Change-Id``. Reuses
   ``mergify_stack::trunk::get_trunk`` (added with ``stack new``)
   and ``mergify_stack::local_commits::read``.
3. Otherwise — ``git rev-parse --verify <commit>^{commit}``.

Then dispatches based on the action:

- ``--remove`` — no-op when the commit has no note (prints
  ``No note on <sha> <subject>.`` and exits 0); otherwise
  ``git notes --ref=refs/notes/mergify/stack remove``.
- ``-m MSG`` (default) — ``git notes … add -f -m MSG``.
- ``-m MSG --append`` — ``git notes … append -m MSG``.
- no ``-m`` — open ``$GIT_EDITOR`` / ``$VISUAL`` / ``$EDITOR``
  / ``vi`` on a tempfile with the comment-line template, strip
  comment lines, treat empty result as ``InvalidState``.

``NOTES_REF`` previously lived on the deleted
``mergify_cli/stack/note.py``. The sole remaining Python
consumer (``stack/push.py``, which pushes the notes ref alongside
the stack branches) carries its own constant now.

Exit-code mapping mirrors Python: ``InvalidState`` for empty
notes and unresolved Change-Id prefixes; ``GenericError`` for
git invocation failures.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: jd

Cargo.lock

@@ -157,6 +157,7 @@ const NATIVE_COMMANDS: &[(&str, &str)] = &[
     ("freeze", "update"),
     ("freeze", "delete"),
     ("stack", "new"),
+    ("stack", "note"),
     // Internal Python migration helpers. Listed so `looks_native`
     // routes `mergify _internal …` past the shim fallback when
     // clap rejects it, but they stay hidden from `--help` (see
@@ -215,6 +216,25 @@ enum NativeCommand {
     /// tracking the resolved trunk. First stack subcommand to land
     /// natively; the rest still shim to Python.
     StackNew(StackNewOpts),
+    /// `mergify stack note [<commit>] [-m <msg>] [--append]
+    /// [--remove]` — attach/append/remove the "why was this commit
+    /// amended" note on `refs/notes/mergify/stack`.
+    StackNote(StackNoteOpts),
+}
+
+struct StackNoteOpts {
+    /// Commit to target — `None` means HEAD. Accepts a SHA prefix,
+    /// a ref (`HEAD~1`, branch name, etc.), or a Change-Id prefix
+    /// (resolved against the stack walk).
+    commit: Option<String>,
+    /// Inline message; `None` means "open `$GIT_EDITOR`". Mutually
+    /// exclusive with `remove`.
+    message: Option<String>,
+    /// Concatenate to the existing note instead of replacing.
+    append: bool,
+    /// Remove the note. Mutually exclusive with `message` /
+    /// `append`.
+    remove: bool,
 }
 
 struct StackNewOpts {
@@ -481,17 +501,26 @@ fn detect_dispatch(argv: &[String]) -> Option<Dispatch> {
 /// subcommands later means adding a branch here and a matching
 /// `NATIVE_COMMANDS` entry.
 fn dispatch_stack(debug: bool, args: Vec<String>) -> Dispatch {
-    if args.first().is_some_and(|a| a == "new") {
-        // `args[0]` is `"new"` — clap consumes it as the program
-        // name in the secondary parse, leaving `args[1..]` as the
-        // actual arguments.
-        let parsed = match StackNewCli::try_parse_from(&args) {
-            Ok(parsed) => parsed,
-            Err(err) => err.exit(),
-        };
-        return Dispatch::Native(NativeCommand::StackNew(StackNewOpts::from(parsed)));
+    match args.first().map(String::as_str) {
+        Some("new") => {
+            // `args[0]` is the subcommand — clap consumes it as
+            // the program name in the secondary parse, leaving
+            // `args[1..]` as the actual arguments.
+            let parsed = match StackNewCli::try_parse_from(&args) {
+                Ok(p) => p,
+                Err(err) => err.exit(),
+            };
+            Dispatch::Native(NativeCommand::StackNew(StackNewOpts::from(parsed)))
+        }
+        Some("note") => {
+            let parsed = match StackNoteCli::try_parse_from(&args) {
+                Ok(p) => p,
+                Err(err) => err.exit(),
+            };
+            Dispatch::Native(NativeCommand::StackNote(StackNoteOpts::from(parsed)))
+        }
+        _ => Dispatch::Shim(inject_global_flags(debug, prepend_one("stack", args))),
     }
-    Dispatch::Shim(inject_global_flags(debug, prepend_one("stack", args)))
 }
 
 #[allow(clippy::too_many_lines)] // mostly mechanical match arms
@@ -1169,6 +1198,48 @@ fn run_native(cmd: NativeCommand) -> ExitCode {
                 }
                 Ok(mergify_core::ExitCode::Success)
             }
+            NativeCommand::StackNote(opts) => {
+                let action = if opts.remove {
+                    mergify_stack::commands::note::Action::Remove
+                } else if let Some(msg) = opts.message {
+                    if opts.append {
+                        mergify_stack::commands::note::Action::Append(msg)
+                    } else {
+                        mergify_stack::commands::note::Action::Set(msg)
+                    }
+                } else {
+                    mergify_stack::commands::note::Action::FromEditor
+                };
+                let outcome = mergify_stack::commands::note::run(
+                    None,
+                    opts.commit.as_deref(),
+                    action,
+                )?;
+                match outcome {
+                    mergify_stack::commands::note::Outcome::Attached { sha, subject } => {
+                        println!(
+                            "Note attached to {short} {subject}.",
+                            short = &sha[..sha.len().min(12)],
+                        );
+                    }
+                    mergify_stack::commands::note::Outcome::Removed { sha, subject } => {
+                        println!(
+                            "Note removed from {short} {subject}.",
+                            short = &sha[..sha.len().min(12)],
+                        );
+                    }
+                    mergify_stack::commands::note::Outcome::NoNoteToRemove {
+                        sha,
+                        subject,
+                    } => {
+                        println!(
+                            "No note on {short} {subject}.",
+                            short = &sha[..sha.len().min(12)],
+                        );
+                    }
+                }
+                Ok(mergify_core::ExitCode::Success)
+            }
             NativeCommand::InternalStackLocalCommits(opts) => {
                 // Run `git log` for the stack range, parse each
                 // commit's `Change-Id:` trailer, emit a JSON array
@@ -1361,6 +1432,50 @@ impl From<StackNewCli> for StackNewOpts {
     }
 }
 
+/// `mergify stack note [<commit>]` — clap definition for the
+/// natively-ported `stack note` subcommand. Same secondary-parse
+/// pattern as `stack new`.
+#[derive(Parser)]
+#[command(
+    name = "note",
+    about = "Attach a 'why was this commit amended' note to a commit"
+)]
+struct StackNoteCli {
+    /// Target commit. Accepts a SHA prefix, a ref (`HEAD~1`,
+    /// branch name, …), or a Change-Id prefix (resolved against
+    /// the stack walk). Defaults to HEAD.
+    commit: Option<String>,
+
+    /// Note message. If omitted, opens `$GIT_EDITOR` /
+    /// `$VISUAL` / `$EDITOR` / `vi` on a tempfile.
+    #[arg(short = 'm', long = "message")]
+    message: Option<String>,
+
+    /// Append to an existing note instead of replacing.
+    #[arg(long = "append", action = clap::ArgAction::SetTrue)]
+    append: bool,
+
+    /// Remove the note on the target commit. Mutually exclusive
+    /// with `--message` and `--append`.
+    #[arg(
+        long = "remove",
+        action = clap::ArgAction::SetTrue,
+        conflicts_with_all = ["message", "append"],
+    )]
+    remove: bool,
+}
+
+impl From<StackNoteCli> for StackNoteOpts {
+    fn from(cli: StackNoteCli) -> Self {
+        Self {
+            commit: cli.commit,
+            message: cli.message,
+            append: cli.append,
+            remove: cli.remove,
+        }
+    }
+}
+
 /// Parse a `REMOTE/BRANCH` argument into its two parts. Matches
 /// the Python `trunk_type` click callback in
 /// `mergify_cli/stack/cli.py`: split on the first `/`, so branch

crates/mergify-cli/src/main.rs

@@ -14,10 +14,11 @@ mergify-core = { path = "../mergify-core" }
 regex = "1"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
+tempfile = "3.14"
 url = "2"
 
 [dev-dependencies]
-tempfile = "3.14"
+temp-env = "0.3"
 tokio = { version = "1", default-features = false, features = ["macros", "rt"] }
 url = "2"
 wiremock = "0.6"

crates/mergify-stack/Cargo.toml

@@ -4,3 +4,4 @@
 //! rest still shim to Python.
 
 pub mod new;
+pub mod note;