Skip to content

Add forge-neutral commit-by-commit and version comparison walkthroughs#135

Open
xortive wants to merge 20 commits into
nkzw-tech:mainfrom
xortive:codiff-review-history
Open

Add forge-neutral commit-by-commit and version comparison walkthroughs#135
xortive wants to merge 20 commits into
nkzw-tech:mainfrom
xortive:codiff-review-history

Conversation

@xortive

@xortive xortive commented Jul 21, 2026

Copy link
Copy Markdown

Background

I like to author MRs/PRs with structured commits that are meant to assist the reviewer in understanding the change, by breaking out refactors or code movement into early commits, and leaving the actual semantic intent of the change for later commits. Combined with stacked diffs, this is my preferred way to submit changes.

However, the native review process for these in the popular git forges is often pretty bad. Some forges like gitlab, implement "version comparison" where a new push or update to the MR's destination generates a new "version", such that you can review the diff between "versions" of your MR. For forges that don't implement this, I would often settle for uploading !fixup commits as a workaround, and squashing them before merge.

This MR introduces many new features intended to make MRs of this nature easier to review.

New features

There's quite a bit of new functionality in this PR intended to improve the experience of using codiff to review MRs in this form:

  • The non-walkthrough "tree" diff viewer, can now review commit(s) in addition to reviewing the entire MR.
    • I suspect this should be a "commit range" and not a list where arbitrary commits can be selected, and need to address that
  • The non-walkthrough "tree" diff viewer, can use version information provided by a git forge, to perform a version comparison. A version comparison is the diff of diffs, i.e. diff(diff(vFrom_start,vFrom_end), diff(vTo_start, vTo_end)).
    • Version comparisons notably do NOT include the diff introduced by a rebase. Any changes to the MR itself to accommodate for conflicts introduced by a rebase will still be shown.
  • Walkthroughs can now be generated commit-by-commit, with separate independent agent generations, run in parallel, for each commit in a MR. A heuristic detects when a MR should be reviewed as a whole, vs commit-by-commit, by looking for target phrases and certain attributes of an MR.
  • Walkthroughs can also be generated when doing a version comparison. Commits of the "to" diff in a version comparison are classified in relation to the "from" diff -- did they change an existing commit? is the commit new? did the commit get moved into the MR base during a rebase? was a commit deleted?
    • All of this context is fed into the walkthrough agent for each commit section in the "to" diff, allowing walkthroughs to guide you through the changes made since your last review.
  • There's some work here to consolidate the UI in codiff with our internal codiff-web deployment.

TODO

So far, I believe I've gotten all of the local equivalents to codiff-web features working against gitlab, and some of the features work using the github provider. There's a few things still missing:

  • version comparisons derived from github force push information
    • I'm unsure if these will be practical -- if old MR heads are not available, it might not be possible to determine the "from" diff in a version comparison. EDIT: I think this is doable... github caches the old MR heads for some time, and we only care about that if they aren't present in the local repo.
  • testing if the web/ share UI supports the new walkthrough variants
  • local skill generated walkthroughs from inside an agent harness do not support the new walkthrough variants. I think this is fine, considering the typical usecase for these.
  • add evals for new walkthrough variants

xortive added 19 commits July 21, 2026 17:24
Render the pull request description, status actions, and reviewer summary inside one consistent overview grid instead of separate nested cards. This keeps the existing data and behavior intact while making the source header reusable across the normal code view and shared review surfaces.
Render the walkthrough arc outside the flexing `.wt-hybrid` content container for every host, matching the existing Web presentation. This keeps chapter navigation visible while the diff body scrolls and removes the local-versus-Web placement distinction.
Introduce forge-neutral revision, range, comparison, evolution, version, and review-plan types plus the constructors and plan-resolution helpers that operate on them. Keeping this domain model independent gives Codiff Web and provider adapters a stable contract before any shared review UI is introduced.
Centralize draft parsing, prompt construction, hunk indexing, normalization, comment attachment, and unit composition in Core. This gives Codiff Web and Electron one deterministic authoring pipeline while leaving model execution, retries, caching, and storage in their respective hosts.
Implement patch-signature generation and confidence-based pairing for commits across rewritten review stacks. The matcher lives in Core so GitLab and GitHub can share retained, revised, removed, ambiguous, and absorbed-into-base classification without duplicating provider logic.
Introduce the GitLab transport abstraction and read-side provider implementation for versions, commit diffs, comparisons, review strategy, and commit evolution. Build the provider on Core review-history contracts and the shared matcher so Codiff Web can supply authenticated HTTP transport without carrying provider logic in its host.
Add focused fixtures for pure rebases, edited rebases, conflict resolutions, strategy classification, and commit pairing. Keeping the high-volume scenario coverage separate makes the provider implementation reviewable while preserving regression coverage for the analysis behavior Codiff Web will depend on.
Describe the shared Core and GitLab APIs, walkthrough-authoring ownership, generation inputs, and the Codiff Web migration checklist. Keep local Electron authentication and IPC guidance out of this document so the foundation MR remains scoped to reusable Web-facing packages.
Resolve review plans into whole-diff or per-unit generation, invoke a host-supplied model runner, normalize each authored result, and compose unit walkthroughs in Core. This lets Codiff Web share one orchestration contract while retaining ownership of model selection, queues, retries, and persistence.
Move commit-evolution projection and shared unit helpers into Core so provider adapters produce the same review-history model. Update the GitLab adapter to consume that shared projection instead of owning provider-specific copies, preparing the API used by Codiff Web and later GitHub integration.
Extend the existing shared review surface with commit and version navigation, whole-diff comparison state, review-history sidebars, and the controls needed to inspect changed files across review iterations. Keep the UI host-driven so Codiff Web can supply provider data without embedding GitLab or local Electron behavior in the components.
Remove shared walkthrough section identifiers from provider-facing comment payloads and recover the rendered diff section from file, side, and line coordinates. Update Core and Codiff Web callers so persisted comments use one provider-neutral contract without losing their in-app placement.
Present introduced, removed, revised, retained, ambiguous, and absorbed commits with consistent labels in tooltips, comparison lists, and walkthrough chapter boundaries. Carry the classification through walkthrough authoring so reviewers can understand why a logical change moved or was rewritten without reading provider-specific metadata.
Expose structured generation progress to the shared review surface and render current phases plus per-unit status while a walkthrough is prepared, generated, and combined. Keep loading and generation messaging host-neutral so Codiff Web can provide useful feedback without coupling the UI to a specific agent runtime.
Introduce the `@nkzw/codiff-github` workspace package with transport contracts, force-push timeline loading, historical comparison tests, and package build configuration. The package is kept separate from Electron wiring so its provider behavior can be reviewed before local Codiff adopts it.
Route local prompt construction, draft normalization, hunk aliasing, and walkthrough composition through the shared Core authoring module. Keep Electron responsible only for agent execution and host concerns so Codiff Web and local Codiff use the same authored walkthrough semantics.
Route pull-request sources through LocalMergeRequestReviewHost so local Codiff
renders MergeRequestReviewApp chrome (tree/walkthrough/comments) instead of the
reduced App.tsx PR path. Baseline whole-PR review, comments, and walkthrough
generation use existing IPC; version compare stays unwired for the next step.
Implement the `GitLabTransport` contract over authenticated `glab api` calls and expose it from the local merge-request backend. This isolates process execution and pagination from the shared GitLab provider package before the review host starts loading version history.
Bridge the shared GitLab provider package into Electron and implement local version, comparison, evolution, and unit-diff loading for merge requests. Keep this backend provider-specific so its CLI transport and projection behavior can be reviewed independently from GitHub force-push handling.
@xortive
xortive force-pushed the codiff-review-history branch from 72c6b64 to 0bf5597 Compare July 21, 2026 23:05
@xortive xortive changed the title Polish shared review-history UI and GitHub evolution Add shared review-history UI Jul 21, 2026
@xortive
xortive force-pushed the codiff-review-history branch 4 times, most recently from 42f52b8 to 0bf5597 Compare July 22, 2026 00:07
@cpojer

cpojer commented Jul 22, 2026

Copy link
Copy Markdown
Member

This PR is not merge-able as is. Please run vpr test:all and fix all the issues. It completely breaks the layout of the app:

CleanShot 2026-07-22 at 11 44 04@2x

There is also a slop list of more issues:

  1. P1 — Commenting on shared working-tree walkthroughs regresses.

    core/SharedWalkthroughApp.tsx:2997 derives commenting capability from source.type ===
    'pull-request'. A signed-in working-tree share can provide onSubmitComment while not being
    a pull request, but core/app/components/ReviewCodeView.tsx:1561 hides submission anyway.

    This should remain capability-based—such as canSubmitReviewComments—rather than source-
    type-based.

  2. P2 — GitLab comment-position comparison can reject a valid fetched comment.

    gitlab/src/history.ts:1007 correctly fetches discussions when a comment-position endpoint
    is requested, but gitlab/src/history.ts:1027 discards those anchors whenever the caller
    supplied any nonempty comment array.

    I reproduced this through the built package: GitLab returned gitlab:42, but supplying an
    unrelated gitlab:7 caused:

    Unknown comment position for version comparison: gitlab:42

    Merge or search both anchor collections instead.

  3. P3 — Unrelated workspace configuration disables VS Code Git.

    .vscode/settings.json:33 adds "git.enabled": false. That disables Git integration for
    everyone using the workspace and appears unrelated to “Build Core when installed from
    Git.”

@xortive
xortive force-pushed the codiff-review-history branch from 4f50ea7 to 8c070bc Compare July 22, 2026 03:44
@xortive xortive changed the title Add shared review-history UI Add shared review history across Codiff Jul 22, 2026
@xortive
xortive force-pushed the codiff-review-history branch from 8c070bc to fb64620 Compare July 22, 2026 03:55
@xortive xortive changed the title Add shared review history across Codiff Add forge-neutral commit-by-commit and version comparison walkthroughs Jul 22, 2026
@xortive
xortive force-pushed the codiff-review-history branch from fb64620 to e815212 Compare July 22, 2026 04:35
Implement GitHub head-timeline, comparison, evolution, and unit-diff loading over `gh` plus local Git objects, then dispatch review-history requests by provider. This keeps GitHub rewrite semantics separate from the GitLab merge-request backend while sharing the same Core review model.

Connect local review history to the shared host

Expose provider-neutral review-history and walkthrough-generation IPC to `LocalMergeRequestReviewHost`, materialize comparison and commit-unit files, and refresh the local repository state after review actions. Wire agent generation progress through Electron at the same integration boundary so the shared progress UI receives coherent host events.

Document local review-history parity and follow-ups

Record the local host architecture, authentication requirements, provider-specific terminology, and remaining review findings after the shared packages are adopted. Keeping these notes at the local MR tip makes deferred Electron and GitHub issues visible without leaking local concerns into the Codiff Web foundation docs.
@xortive
xortive force-pushed the codiff-review-history branch from e815212 to e64db1a Compare July 22, 2026 04:40
@xortive

xortive commented Jul 22, 2026

Copy link
Copy Markdown
Author

fixed vpr test:all and pushed up the remaining commits to get the local app working again, and added a real, old school, MR description :) I'll add some screenshots tomorrow

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants