move-diff 0.3.1

Render a git diff with extra markers for moved and reformatted code
Documentation
# AGENTS.md

`move-diff` is a Rust CLI that renders a local `git diff` with extra markers for
moved (`>`/`<`) and reformatted (`x`) code, so large mechanical refactors are
easier to review. It is a drop-in replacement for `git diff`.

## Build / test / lint

- Build: `cargo build` (or `cargo build --release`)
- Test: `cargo test` — all tests are fast and pure (no network). Run a subset
  with `cargo test <substring>`.
- Full local check (what `make check` runs, mirroring CI intent):
  `cargo fmt` → `cargo clippy --all-targets --all-features -- --deny warnings` → `cargo deny check`
  (`cargo deny` is a separate tool; install with `cargo install cargo-deny` if missing).
- Requires a recent rustc (edition 2024, i.e. **rustc >= 1.85**).

## Architecture

Deliberately tiny — four direct dependencies (`anyhow`, `clap`, `duct`,
`patch`) for the `move-diff` binary itself. There is also a `lib` target and
a feature-gated fifth binary purely for regenerating a documentation image
(see below); neither adds a dependency or affects a normal build/install.

- `src/main.rs` — clap `Parser` (flat, no subcommands) plus `main`, which owns
  the exit-status contract.
- `src/git.rs` — the only git plumbing: `local_diff(dir, args)`. There is
  no remote-URL parsing, branch validation, or provider detection here; this
  crate never talks to a hosting provider.
- `src/annotate_diff.rs` — the renderer. `render(diff, max_move_gap, color)`.
- `src/diff_parse.rs` — `split_file_diffs` / `parse_patches_safely`, safe
  wrappers around the `patch` crate.
- `src/lib.rs` — `pub mod annotate_diff;` only (`diff_parse` stays private;
  it's `annotate_diff`'s implementation detail). Exists so `main.rs` and
  `src/bin/svg.rs` share one copy of the renderer instead of `main.rs`
  declaring its own private `mod` tree. Not meant as a public API for other
  crates — it's not published, and `diff_parse` isn't exposed.
- `src/bin/svg.rs` — regenerates `docs/example.svg` from `docs/example.diff`
  by calling the real `annotate_diff::render(..., color: true)` and
  converting the ANSI output to SVG `<tspan>` elements. Gated behind the
  `svg-gen` feature (`required-features` in `Cargo.toml`), so `cargo
  build`/`cargo install` never compiles it. It exists because neither GitHub
  nor GitLab's markdown renders ANSI escapes or `style` attributes, and
  GitLab's `diff` syntax highlighting doesn't understand this tool's `x`
  marker or its no-space `>`/`<` forms — a committed image is the only way
  to show this tool's actual five-marker coloring in a rendered README.
  Regenerate with `cargo run --features svg-gen --bin move-diff-svg --
  docs/example.diff docs/example.svg` after changing `docs/example.diff` or
  the renderer's color codes.


## Non-obvious design points

- **Empty diff is success, not an error.** `main` returns `ExitCode::SUCCESS`
  with no output when the diff is empty, matching `git diff`. The sibling
  `mr-review` bails with "nothing to review" in the same situation — that
  message was deliberately *not* carried over, because erroring on a clean tree
  breaks pipelines and editor integrations.
- **Exit 128 for fatal git errors.** Matches git's own convention for an
  unknown revision, so wrapper scripts can distinguish it from a normal empty
  result.
- **Broken pipe is not an error.** `render` writes via `stdout().lock()` and
  swallows `ErrorKind::BrokenPipe`, so `move-diff … | head` exits quietly
  instead of panicking. Don't replace the locked-write helper with `print!`.
- **`--no-color` goes to git too, not just to us.** If a user has
  `color.diff = always` set, the captured diff would arrive pre-wrapped in ANSI
  escapes and every hunk line would fail to parse. `git.rs` passes `--no-color`
  to git for this reason.
- **`duct`'s `.read()` strips the trailing newline** (like shell `$()`), but the
  `patch` crate's parser *panics* via an internal `assert!` if the last line
  isn't newline-terminated. `annotate_diff::render` restores the newline at its
  top; there's a regression test for it.
- **Output is reconstructed, not echoed.** `render` re-emits `---`/`+++`/`@@`
  headers in its own format rather than preserving the input byte-for-byte, and
  drops the `diff --git`/`index` preamble. That's inherent to the ported design
  (asserted in `annotate_diff.rs`'s tests) — don't "fix" it by string-patching
  the original diff back in.
- **Panics are caught, never propagated.** `parse_patches_safely` wraps
  `Patch::from_multiple` in `catch_unwind` because the `patch` crate `assert!`s
  (rather than returning `Err`) on input it doesn't model — binary diffs,
  mode-only changes, pure renames. Per-file parsing means one unparseable file
  only costs that file.

## Testing quirks

- `src/git.rs` tests shell out to real `git` and therefore depend on the crate
  living inside a git repository (`local_diff` against `.`). They assert on
  behaviour, not output text, so they stay stable.
- The `catch_unwind` in `diff_parse` deliberately does **not** touch the global
  panic hook, to avoid racing with tests running in parallel. A caught panic
  still prints a default backtrace to stderr, which shows up as noise in test
  output — that's expected, not a failure.

## CI

`.gitlab-ci.yml` pulls four `to-be-continuous` components — `docker@8`
(buildah, publishes to `registry.gitlab.com/loikki/move-diff`), `gitleaks@2`,
`rust@1`, and `semrel@4` — and adds two jobs of its own (`binary-build`,
`release-assets`). There is no in-repo pipeline script — the components generate
the rest. `make check` is the closest local equivalent.

The docker build is pinned to amd64 via `build-args: --platform linux/amd64`;
the multi-arch amd64+arm64 variant is only worth turning back on if it doesn't
reintroduce the QEMU slowness (arm64 images are cross-compiled under emulation,
and `mr-review`'s equivalent job hit GitLab's 1-hour limit doing this). If you
do re-enable arm64, either add a `timeout` override to the docker job or keep
the platform flag.

### Releases

One tag drives everything, and `semrel@4` is what creates it:

1. **A `fix:`/`feat:`/`perf:` merge to `main`** → the `semantic-release` job
   derives the next version from conventional commits, runs `prepare.sh`
   (bump `version` in `Cargo.toml`/`Cargo.lock`), commits that plus
   `CHANGELOG.md` back with `[skip ci on prod]` (so the back-push doesn't
   re-trigger the pipeline), then tags and creates the GitLab Release.
2. **That tag push** starts a second pipeline, which is where the rest lives:
   `binary-build` cross-compiles the release archives, `rust-publish` sends the
   crate to crates.io, and `release-assets` uploads the archives onto the
   Release.

`to-be-continuous` has no job for "attach binaries to a GitLab Release", so
`binary-build`/`release-assets` are ours. Three things there are load-bearing:

- **semantic-release must own the tag.** Its job carries
  `- if: $CI_COMMIT_TAG → when: never`, so it can only ever tag from a
  main-branch pipeline. A hand-pushed tag yields a Release that nothing ever
  attaches anything to.
- **It needs `GITLAB_TOKEN` (a project access token, `api` +
  `write_repository`, protected), not `CI_JOB_TOKEN`.** GitLab deliberately
  doesn't start pipelines for pushes made with the job token — with it, the tag
  exists but no tag pipeline follows, so there are no binaries and no crates.io
  publish. Corollary: leave *Settings → CI/CD → "Allow CI push requests"*
  **off**; when it's on, GitLab forces semantic-release back onto the job token
  even if a token is configured, and the tag pipeline silently never runs.
- **The `release:` job keyword can't be used** — it fails outright when the
  release already exists, and semantic-release created it. `release-assets` uses
  `glab release upload` with `GLAB_ENABLE_CI_AUTOLOGIN`, i.e. the job token,
  which has access to the whole Releases API.

`binary-build` extends the rust component's `.rust-base` and overrides `image`
with `rust:1-bookworm`; the cross toolchains are plain apt packages +
`rustup target add`, deliberately *not* `cross` (it would need a Docker socket,
which shared runners don't have). Consequences worth remembering: the
`x86_64-pc-windows-gnu` build needs `-C target-feature=+crt-static` (which is why
`mingw-w64` is installed) to produce a standalone `.exe`, and the
`aarch64-unknown-linux-gnu` tarball links against glibc, so it has a glibc
floor rather than being static. macOS is deliberately absent: `cross` has no
prebuilt Apple images and gitlab.com has no macOS runners.

The version in `Cargo.toml` is the single source of truth, which is why
`binary-build` fails fast when it doesn't equal `$CI_COMMIT_TAG`, and why
step 1's bump has to happen in `prepare` (before the tag exists) rather than in
the tag pipeline. Don't hand-edit the version.

Two conventions that the release flow depends on: commits on `main` follow
conventional commits (`fix:`/`feat:`/`chore:`), and the baseline tag `0.1.0`
exists so the first real release computes as `0.1.1`. Without that tag,
semantic-release sees the whole history (including `feat:` commits) as
unreleased and jumps to `1.0.0`.