Update patch command

[spoorcc]

Fixes #614

Summary by CodeRabbit

• New Features

  • New update-patch command to safely regenerate and overwrite the last patch per project (backups, per-project reporting, patch-count limit).
  • CLI subcommand names now normalize to kebab-case.
  • Reverse-diff support and VCS local-change detection (Git/SVN) to improve patch generation and validation.

• Documentation

  • Manual entry, asciicast and demo script demonstrating the update-patch workflow.

• Tests

  • Extensive reverse_patch unit tests and new BDD scenarios exercising update-patch for Git and SVN.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds a new update-patch CLI command and implementation; introduces patch reversal utilities and reverse-diff support; extends SuperProject/SubProject/VCS APIs (reverse diffs, patch_count, any_changes helpers); and adds tests, BDD features, docs, and demo scripts.

Changes

Cohort / File(s)	Summary
CLI & command registration dfetch/__main__.py, dfetch/commands/command.py, dfetch/commands/update_patch.py	Register new UpdatePatch command; add pascal_to_kebab() for CLI name normalization; implement update-patch subcommand and menu.
Core project model dfetch/project/superproject.py, dfetch/project/subproject.py	Add in_vcs(), is_git(), has_local_changes_in_dir(), current_revision() to SuperProject; add patch property, patch_count support, and propagate reverse through SubProject diff/update methods.
Subproject VCS adapters dfetch/project/git.py, dfetch/project/svn.py	Add reverse parameter to subproject diff implementations; forward to LocalRepo create_diff; apply reverse-patch handling for untracked-file patches and SVN-specific reversal logic.
Local repo & patch utilities dfetch/vcs/git.py, dfetch/vcs/svn.py, dfetch/vcs/patch.py	Add reverse-diff support to LocalRepo.create_diff (Git uses -R + swapped prefixes); implement reverse_patch() to invert patches; add any_changes_or_untracked() helpers for Git and SVN.
Update-patch flow dfetch/commands/update_patch.py, dfetch/project/...	New command flow: validate superproject VCS, check per-project local changes, compute reverse diff for the last patch, backup & overwrite last patch file if diffs exist, and reapply/update patches; aggregate per-project errors.
Tests & BDD tests/test_patch.py, tests/test_subproject.py, tests/test_fuzzing.py, features/..., features/steps/*.py	Add extensive reverse_patch tests (including Hypothesis); adjust test signature for reverse flag; add Git/SVN update-patch feature files; add Behave steps (rename, commit-all alias, add-and-commit).
Docs & demos CHANGELOG.rst, doc/manual.rst, doc/asciicasts/update-patch.cast, doc/generate-casts/*, doc/generate-casts/update-patch-demo.sh	Document the new update-patch command, add asciinema cast and demo script, and add changelog entry.
Minor cleanup dfetch/commands/diff.py, tests/test_fuzzing.py	Remove obsolete doc block and a redundant blank line; small formatting/doc edits.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant CLI as "CLI (update-patch)"
    participant SP as "SuperProject"
    participant Sub as "SubProject"
    participant VCS as "Git/SVN LocalRepo"
    participant Patch as "vcs.patch.reverse_patch"

    User->>CLI: run update-patch <project(s)>
    CLI->>SP: in_vcs()
    SP-->>CLI: True/False
    CLI->>SP: has_local_changes_in_dir(proj_path)
    SP->>VCS: any_changes_or_untracked(path)
    VCS-->>SP: bool
    alt proceed
        CLI->>Sub: update(patch_count = last_patch_index)
        CLI->>Sub: diff(old_rev, current_rev, reverse=true)
        Sub->>VCS: create_diff(old, new, ignore, reverse=true)
        VCS-->>Patch: raw diff bytes
        Patch->>Patch: reverse_patch(bytes)
        Patch-->>CLI: reversed diff text
        alt diff produced
            CLI->>Sub: backup & overwrite last patch file
            CLI->>Sub: update(patch_count=-1)
            CLI-->>User: "Patch updated"
        else no diff
            CLI-->>User: "No diffs found"
        end
    else skip
        CLI-->>User: "Skipped: local changes / no patch / not fetched"
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• #956 — modifies subproject.py diff/_diff_impl signatures and related parameters; strong overlap.
• #942 — introduces per-patch application helpers and adjustments to patch handling in subproject.py.
• #931 — changes patch handling and update/apply logic in SubProject, related to this PR's behavior.

Suggested labels

enhancement, development

Suggested reviewers

• ben-edna

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Update patch command' clearly summarizes the main change: introduction of a new dfetch update-patch subcommand.
Linked Issues check	✅ Passed	The PR implements the core functionality requested in #614: a dedicated update-patch command that detects local changes, updates projects to fetched versions, generates reverse diffs, and regenerates patches.
Out of Scope Changes check	✅ Passed	All changes are scoped to implementing the update-patch command and supporting infrastructure. No unrelated modifications to other features or components are present.
Docstring Coverage	✅ Passed	Docstring coverage is 81.67% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch update-patch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@tests/test_patch.py`:
- Around line 298-315: The test currently passes in-memory strings to
apply_patch but apply_patch expects a patch file path and works against files
under a root directory; update the test to write patch_forward to a temporary
patch file and write the modified content to a real temp file (use the tmp_path
fixture), then call apply_patch with the patch file path (and root=tmp_path if
required) to produce restored and assert restored file contents equal original;
reference the existing symbols patch_forward, reverse_patch, apply_patch,
modified, original, and restored when locating where to change the test.
- Around line 6-12: The property test currently calls random.choice() and
random.shuffle() inside a `@given` test which prevents Hypothesis from controlling
randomness; replace direct random module calls by drawing a Hypothesis-managed
RNG via st.randoms() and use that RNG (the Random instance returned) for .choice
and .shuffle calls. Locate the failing test (the `@given-decorated` function that
uses random.choice and random.shuffle) and add a parameter drawn from
st.randoms(), then replace random.choice(...) and random.shuffle(...) with
rng.choice(...) and rng.shuffle(...), keeping the existing st imports
(st.randoms) so Hypothesis can reproduce and shrink failures.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@dfetch/commands/update_patch.py`:
- Around line 126-132: The reverse patch is being generated with old_revision=""
which diffs against the working tree and can become empty; change the call to
subproject.diff in update_patch.py so that when reverse=True you pass the
superproject's current revision (use superproject.current_revision()) as
old_revision instead of an empty string (and keep new_revision as before),
ensuring the reverse diff is computed against the superproject commit context.

In `@dfetch/vcs/svn.py`:
- Around line 206-211: In get_last_changed_revision, the directory check uses
the original target instead of the stripped string; change the os.path.isdir
call to use the computed target_str (or resolve/str() the Path into target_str)
so the isdir check and subsequent svnversion invocation operate on the same,
whitespace-trimmed path (update the os.path.isdir(target) reference in
get_last_changed_revision to os.path.isdir(target_str)).