Files
kandev/apps/backend/internal/review/resolver.go
T
João Salavisa 57adf1449c feat(review): native code-review agent with inline findings in the Changes panel (#1957)
* feat(review): persist and publish native code-review findings

Adds the backend core for reviewing a task's working diff before a PR
exists: task-scoped review runs and anchored, advisory findings that the
Changes/Review panel can render as inline comments.

- task_review_runs / task_review_findings schema, models, and repository,
  with supersede-on-re-review and a restart sweep that cancels in-flight
  runs rather than leaving them looking alive.
- ReviewService as the single write path, publishing bus events that the
  WS gateway forwards to the client.
- internal/review: reviewer-identity resolution (agent profile > code-review
  utility agent > user default, failing closed on passthrough-only profiles),
  change-set collection, prompt batching, response parsing, anchor
  extraction, and run orchestration.
- publish_review_findings_kandev MCP tool plus the task.review.* WS actions.
- Go djb2 that matches apps/web/lib/utils/hash.ts, asserted from shared
  fixtures on both sides so stale detection agrees across the wire.

Spec: docs/specs/native-code-review/spec.md
Plan: docs/plans/native-code-review/plan.md

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(review): add run_code_review workflow step and wire the review runner

Makes a review pass triggerable both ways and actually runnable end to end.

- run_code_review on_enter action across models, engine compile, and an
  orchestrator callback that logs rather than propagates failures, so a task
  never gets stuck in a step because no reviewer was configured.
- The step's optional agent_profile_id is what lets a step review with a
  different model than it implemented with; export/import swap it for a
  portable agent name/model/mode so it survives a cross-workspace round trip
  instead of carrying a dangling id.
- Concrete adapters for reviewer identity, changed-file collection, prompt
  rendering from the code-review utility agent's editable prompt, and
  inference (session-bound agentctl, falling back to the host instance so a
  review works on a task whose agent is not running).
- Boot sweep cancels review runs interrupted by a restart; the E2E reset
  clears review state before deleting the tasks that own it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(web): add review findings state, helpers, and live updates

Frontend plumbing for native code review, ahead of the UI that renders it.

- Review types, WS message map, and an API client that preserves the backend's
  machine-readable failure code so the surface can show an actionable message.
- A review store slice that merges findings by id (a re-publish refreshes an
  issue rather than listing it twice) and keeps a bounded run history.
- Findings helpers: composite file keys matching reviewFileKey, staleness via
  the same per-file diff hash that drives review marks, and best-effort
  re-anchoring from the stored anchor text so a moved finding follows the code
  it was written about instead of pointing at whatever now occupies its line.
- Hooks for backfill, resolve/dismiss/reopen with optimistic rollback, and
  sending a finding to the agent as follow-up context without changing its
  status — handing a finding to an agent is not the human accepting it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(web): render review findings inline in the Changes diff

Findings now appear where the code is, in the same annotation surface as
anchored review comments, with the run control that produces them.

- ReviewFindingCard: severity chip, category, Markdown body, and the three
  advisory actions. A suggestion is labelled "not applied automatically"
  because it is display-only in this iteration. Resolved and dismissed
  findings collapse to one muted line with an Undo, so a reviewed diff does
  not stay cluttered while the human can still change their mind.
- A review-finding annotation type threaded through the diff viewer, anchored
  from the same per-file diff hash the backend stamped. A finding whose diff
  moved is re-anchored from its stored text when that text survives, and
  otherwise reported as unanchored rather than placed against unrelated code.
- Review changes control with idle / running / cancel / failed states, and an
  inline Settings link for the one failure the user can actually fix.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(web): make the review control reachable from the Review toolbar

Mounts the Review changes control next to the walkthrough action and lets an
inline finding wire its own actions.

The finding card container now reads the active task and session from the store
instead of taking four callbacks threaded through FileDiffViewer and DiffViewer;
an inline finding annotation only exists when the active task has findings, so
the store is always present and every other diff consumer is spared the
plumbing. Staleness likewise hashes the diff the viewer already holds, which is
already normalized, so it matches the hash the backend stamped without passing
it down.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* feat(web): surface stale review findings above their file's diff

A finding whose diff moved and whose anchor text is gone had nowhere to render,
so it was silently dropped. It now appears in a collapsed per-file banner above
the diff: the finding may still be valid, and placing it at its stored line
would point at whatever code now occupies that line instead.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* docs(review): mark the landed native code-review plan tasks done

Tasks 01-09 (backend persistence through inline diff rendering) are
implemented, tested, and committed. Tasks 10-13 — findings overview and step
editor, mobile parity, E2E, and public docs — remain pending.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* test(review): cover the on-demand review path end to end

Adds the mock-agent review responder and a Playwright spec, so both the happy
path and the no-reviewer path are verified against a real backend.

The mock agent answers any prompt carrying the review sentinel with fenced JSON,
deriving its anchors from the prompt's own diff rather than hardcoding them, so
findings land on files and lines the fixture really changed. It includes one
deliberately malformed entry to exercise the rejected-entry path.

Writing it caught an off-by-one shared by three diff walkers: splitting on "\n"
leaves an empty element after a trailing newline, which carries no diff marker
and was being counted as a context line, pushing new-side numbering one past the
end of a hunk. Interior blank lines still count, since a whitespace-stripped
blank context line legitimately appears as "".

Also adds a listInferenceAgents helper: default_utility_agent_id needs the
registered agent-type id, and an agent row UUID is rejected as not
inference-capable.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(review): close review-run races and stale client findings

Addresses the three blockers and three suggestions from the PR #1957 automated
reviews. Two independent reviewers found each blocker separately.

- Launch claimed the task slot only after inserting the run row, so two
  concurrent launches both created a run and the loser returned a pending row
  with no goroutine behind it — a review that never finished until the next
  restart. The slot is now claimed before any DB write, and freed on every
  early return.
- Cancelling only marked the row. The goroutine ran on the shared background
  context, finished inference, and its completion overwrote the cancelled
  status and published findings the user had declined. Runs now carry a cancel
  handle, the WS action routes through the runner so the live context is
  cancelled, CompleteRun/FailRun refuse to resurrect a terminal run, and a
  cancelled pass neither publishes nor re-reports itself as failed.
- The backend deletes a superseded finding and inserts a replacement with a new
  id, but the publish event carried only the new one, so every open browser
  showed both at the same anchor until a reload. The event now names the
  superseded ids and the slice drops them.
- Run() waited on the shared WaitGroup, blocking on every other task's review;
  it now waits on its own pass only.
- createReviewSlice is typed over the `set` it actually uses, so call sites no
  longer pass superfluous arguments (CodeQL js/superfluous-trailing-arguments).
- A GetAgentProfile fault no longer collapses into "profile not found", which
  would have told the user to configure an agent they already have.

The cancel bug exposed a hole in the original tests: they asserted cancel could
not override a terminal run, but never the reverse. Both directions are covered
now, along with the concurrent-launch race, per-run waiting, and the supersede
path on both sides of the wire. Test fakes now mirror the service's terminal
guard rather than hiding it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-26 15:05:56 +01:00

222 lines
8.3 KiB
Go

package review
import (
"context"
"errors"
"fmt"
"strings"
)
// ReviewerIdentity is the (agent CLI, model, mode) triple a review pass runs as.
// It is deliberately separate from the task's own agent profile: the point of the
// feature is that a different model can review than implemented.
type ReviewerIdentity struct {
AgentID string
Model string
Mode string
// Source names where the identity came from, for the run record and logs:
// "agent_profile", "utility_agent", or "user_default".
Source string
}
// Identity sources.
const (
SourceAgentProfile = "agent_profile"
SourceUtilityAgent = "utility_agent"
SourceUserDefault = "user_default"
)
// ReviewerProfile is the subset of an agent profile the resolver needs.
type ReviewerProfile struct {
AgentID string
Model string
Mode string
CLIPassthrough bool
Name string
}
// ProfileLookup resolves an agent profile ID. Returns found=false for an unknown
// profile.
type ProfileLookup interface {
ReviewerProfile(ctx context.Context, profileID string) (profile ReviewerProfile, found bool, err error)
}
// UtilityAgentLookup resolves the built-in `code-review` utility agent, which
// supplies the default reviewer identity for the on-demand path.
type UtilityAgentLookup interface {
// CodeReviewAgent returns the code-review utility agent's agent/model and
// whether it is enabled. found=false means the row is missing entirely.
CodeReviewAgent(ctx context.Context) (agentID, model string, enabled, found bool, err error)
}
// DefaultsLookup resolves the user's default utility agent/model pair, used when
// the code-review utility agent leaves the model blank.
type DefaultsLookup interface {
DefaultUtilitySettings(ctx context.Context) (agentID, model string, err error)
}
// Resolver picks the reviewer identity for a run.
type Resolver struct {
Profiles ProfileLookup
Utility UtilityAgentLookup
Defaults DefaultsLookup
}
// NewResolver builds a resolver. Any lookup may be nil; a nil lookup simply
// contributes no candidate identity.
func NewResolver(profiles ProfileLookup, utility UtilityAgentLookup, defaults DefaultsLookup) *Resolver {
return &Resolver{Profiles: profiles, Utility: utility, Defaults: defaults}
}
// Resolve returns the reviewer identity for a run.
//
// Precedence:
// 1. an explicit agent profile (the workflow-step path), which is what makes a
// per-step reviewing model possible;
// 2. the enabled built-in `code-review` utility agent;
// 3. the user's default utility agent/model.
//
// The agent/model pair is treated as inseparable: a default model from one
// provider must never be sent to another provider's ACP config, so a blank model
// pulls both halves from the defaults rather than just the model.
//
// Fails closed with ErrAgentUnavailable — never guesses an agent — because a
// wrong provider/model pair produces either a hard provider error or, worse, a
// confident review from a model the user did not choose.
func (r *Resolver) Resolve(ctx context.Context, agentProfileID string) (ReviewerIdentity, error) {
if strings.TrimSpace(agentProfileID) != "" {
return r.resolveFromProfile(ctx, strings.TrimSpace(agentProfileID))
}
identity, err := r.resolveFromUtilityAgent(ctx)
if err == nil {
return identity, nil
}
// Only an absent or disabled code-review agent defers to the user defaults.
// A configured-but-inconsistent one is a hard failure: falling back there
// would quietly review with a provider/model pair the user never chose.
if !errors.Is(err, errDeferToDefaults) {
return ReviewerIdentity{}, err
}
return r.resolveFromDefaults(ctx)
}
// errDeferToDefaults marks the "code-review utility agent is absent or turned
// off" case, where falling back to the user's default agent/model is correct.
var errDeferToDefaults = errors.New("defer to default utility settings")
func (r *Resolver) resolveFromProfile(ctx context.Context, profileID string) (ReviewerIdentity, error) {
if r.Profiles == nil {
return ReviewerIdentity{}, fmt.Errorf("%w: agent profiles are not available", ErrAgentUnavailable)
}
profile, found, err := r.Profiles.ReviewerProfile(ctx, profileID)
if err != nil {
return ReviewerIdentity{}, fmt.Errorf("%w: load agent profile %s: %v", ErrAgentUnavailable, profileID, err)
}
if !found {
return ReviewerIdentity{}, fmt.Errorf("%w: agent profile %s no longer exists", ErrAgentUnavailable, profileID)
}
if profile.CLIPassthrough {
return ReviewerIdentity{}, fmt.Errorf(
"%w: agent profile %q is CLI-passthrough only and cannot run a structured review",
ErrAgentUnavailable, describeProfile(profile, profileID))
}
if profile.AgentID == "" {
return ReviewerIdentity{}, fmt.Errorf("%w: agent profile %q has no agent configured",
ErrAgentUnavailable, describeProfile(profile, profileID))
}
model := profile.Model
if model == "" {
// The profile names an agent but no model; borrow the user's default
// model only when it belongs to the same agent.
model = r.sameAgentDefaultModel(ctx, profile.AgentID)
}
if model == "" {
return ReviewerIdentity{}, fmt.Errorf("%w: agent profile %q has no model configured",
ErrAgentUnavailable, describeProfile(profile, profileID))
}
return ReviewerIdentity{
AgentID: profile.AgentID,
Model: model,
Mode: profile.Mode,
Source: SourceAgentProfile,
}, nil
}
func describeProfile(profile ReviewerProfile, profileID string) string {
if profile.Name != "" {
return profile.Name
}
return profileID
}
// sameAgentDefaultModel returns the user's default model only when the default
// belongs to agentID, so a model is never crossed between providers.
func (r *Resolver) sameAgentDefaultModel(ctx context.Context, agentID string) string {
if r.Defaults == nil {
return ""
}
defaultAgent, defaultModel, err := r.Defaults.DefaultUtilitySettings(ctx)
if err != nil || defaultAgent != agentID {
return ""
}
return defaultModel
}
func (r *Resolver) resolveFromUtilityAgent(ctx context.Context) (ReviewerIdentity, error) {
if r.Utility == nil {
return ReviewerIdentity{}, fmt.Errorf("%w: %w: no code-review utility agent is wired",
ErrAgentUnavailable, errDeferToDefaults)
}
agentID, model, enabled, found, err := r.Utility.CodeReviewAgent(ctx)
if err != nil {
// A lookup failure is a real fault, not an unconfigured feature; do not
// mask it by silently reviewing with the defaults.
return ReviewerIdentity{}, fmt.Errorf("%w: load code-review utility agent: %v", ErrAgentUnavailable, err)
}
if !found {
return ReviewerIdentity{}, fmt.Errorf("%w: %w: the code-review utility agent is missing",
ErrAgentUnavailable, errDeferToDefaults)
}
if !enabled {
return ReviewerIdentity{}, fmt.Errorf("%w: %w: the code-review utility agent is disabled",
ErrAgentUnavailable, errDeferToDefaults)
}
// A configured utility agent with a blank model means "use my defaults";
// take the agent and model together so the pair stays consistent.
if model == "" {
defaults, defErr := r.resolveFromDefaults(ctx)
if defErr != nil {
return ReviewerIdentity{}, defErr
}
if agentID == "" {
agentID = defaults.AgentID
}
if agentID != defaults.AgentID {
return ReviewerIdentity{}, fmt.Errorf(
"%w: the code-review utility agent uses %s but the default model belongs to %s; set a model on the code-review agent in Settings > Utility Agents",
ErrAgentUnavailable, agentID, defaults.AgentID)
}
return ReviewerIdentity{AgentID: agentID, Model: defaults.Model, Source: SourceUtilityAgent}, nil
}
if agentID == "" {
return ReviewerIdentity{}, fmt.Errorf("%w: the code-review utility agent has no agent configured", ErrAgentUnavailable)
}
return ReviewerIdentity{AgentID: agentID, Model: model, Source: SourceUtilityAgent}, nil
}
func (r *Resolver) resolveFromDefaults(ctx context.Context) (ReviewerIdentity, error) {
if r.Defaults == nil {
return ReviewerIdentity{}, fmt.Errorf("%w: no default utility agent is configured", ErrAgentUnavailable)
}
agentID, model, err := r.Defaults.DefaultUtilitySettings(ctx)
if err != nil {
return ReviewerIdentity{}, fmt.Errorf("%w: load default utility settings: %v", ErrAgentUnavailable, err)
}
if agentID == "" || model == "" {
return ReviewerIdentity{}, fmt.Errorf(
"%w: no inference-capable agent and model are configured; set one in Settings > Utility Agents",
ErrAgentUnavailable)
}
return ReviewerIdentity{AgentID: agentID, Model: model, Source: SourceUserDefault}, nil
}