Files
kandev/docs/plans/gitlab-mr-task-list-badges/plan.md
T
2026-08-24 11:09:03 +00:00

342 lines
17 KiB
Markdown

---
spec: docs/specs/integrations/requirements/gitlab-mr-task-list-badges.md
created: 2026-08-13
status: draft
---
# Implementation Plan: GitLab MR Badge on the Sidebar and Tasks-List Rows
> **Amendment:** The later
> [rich task title preview plan](../rich-task-title-previews/plan.md) extends
> this plan. It owns rich badge content and shared hydration behavior.
## Overview
`MRTaskIcon` ships today with exactly one call site (the Kanban card). This plan
adds it to the two remaining task-row surfaces: the app sidebar row
(`components/task/task-item.tsx`) and the `/tasks` rich row
(`app/tasks/rich-task-list-row.tsx`), and gives `/tasks` its own unconditional MR
hydration call so its own row has data to render. Frontend only: no backend, no
API, no store slice, no new component, no new user-facing copy.
The three production edits are on disjoint files and can land in any order; the
three E2E specs follow them. The order below is dependency order, not risk order:
each surface is independently observable, so the product is working after every
task.
---
## Backend
None. The spec introduces no persistent state, no API, no WS action, and no
change to `TaskStatusSummary`. The GitLab MR rows the badge reads are already
cached at `taskMRs.byWorkspaceId[workspaceId][taskId]`.
---
## Frontend
### 1. App sidebar row — `apps/web/components/task/task-item.tsx`
The local `TaskPRIcon` component (currently at ~line 314) is two chained early
returns:
```tsx
const hasStorePR = useAppStore((s) => !!taskId && (s.taskPRs.byTaskId[taskId]?.length ?? 0) > 0);
if (hasStorePR) return <PRTaskIcon taskId={taskId!} />;
if (!prInfo) return null;
// ... prInfo fallback badge
```
Both `return`s exit the component, so anything appended after them is
unreachable for a task that has a PR **and** for a task that has neither a PR nor
`prInfo` — the GitLab-only task this feature exists to serve.
Restructure so the PR branch and the MR branch are siblings. Rename the component
to reflect that it now renders both contribution badges, and have it return a
fragment:
```tsx
function TaskContributionIcons({ taskId, prInfo }: { taskId?: string; prInfo?: PrInfo }) {
const hasStorePR = useAppStore((s) => !!taskId && (s.taskPRs.byTaskId[taskId]?.length ?? 0) > 0);
return (
<>
<TaskPRBadge taskId={taskId} prInfo={prInfo} hasStorePR={hasStorePR} />
{taskId ? <MRTaskIcon taskId={taskId} /> : null}
</>
);
}
```
Three rules the restructure must hold, each with its own AC:
- The MR branch needs **its own `taskId` truthiness guard**. `hasStorePR` is not
usable: it is `false` both when `taskId` is absent and when `taskId` is present
with no PRs. `<MRTaskIcon taskId={taskId!} />` (the non-null-assertion shape the
PR branch beside it uses) would invoke the component with `undefined`, add a
`useTaskMRs` subscription, and violate AC5 and AC18 while still rendering
nothing. The guard must prevent the call, not just the output. (AC5, AC18)
- The call site inside `TaskItemContent`'s title row keeps its position: the MR
badge lands immediately after the PR badge and **before** `IssueTaskIcon`.
Full row order: title, autopilot, pinned, **PR, MR**, issue, agent-error,
remote-cloud, archived chip. (AC2, AC22)
- The sidebar hydrates nothing. No file under `components/task/` or
`components/app-sidebar/` may import `useWorkspaceMRs`. (AC7)
`task-item.tsx` measures **591 effective lines** against the 600-line
`max-lines` limit (`skipBlankLines`, `skipComments`, `--max-warnings 0`). The
restructure above fits inline with margin; the one-new-file allowance in the
spec's Constraints is a fallback, not the expected shape.
### 2. `/tasks` rich row — `apps/web/app/tasks/rich-task-list-row.tsx`
In `PrimaryTaskLine`:
- Rename the prop `showPullRequest: boolean` to `showContributions: boolean`.
It is file-local (declared and passed only within this file: `true` from
`RichTaskContent` at ~line 129, `false` from `TaskListRowPrimaryContent`'s
compact path at ~line 174). One flag gates both badges; no second flag, no
per-provider toggle, and no default value. No `showPullRequest` identifier may
remain in the file. (AC10, AC11)
- Add `<MRTaskIcon taskId={task.id} />` **inside the existing**
propagation-stopping `<span>` that already wraps `PRTaskIcon`, after it. Not a
second wrapper: one wrapper, two children, so the badges cannot drift apart on
interaction behaviour. (AC9)
- That wrapper carries **no `className` today** because it has only ever had one
child. Two children would render with no separation at all. Give it
`inline-flex items-center gap-1` — the same `gap-1` the Kanban card's
`kanban-card-title-row` and the sidebar title row already use. Apply it
**unconditionally**, so it adds no element and reserves no space in the no-MR
case. (AC23, and this is why AC23 and AC6 are not in tension)
- Do not add `shrink-0` (both badge roots already carry it) and do not touch the
row's existing `gap-2`.
### 3. `/tasks` hydration — `apps/web/app/tasks/tasks-page-client.tsx`
The page already owns its GitHub hydration, gated on the same setting that gates
the badge (line 529):
```ts
useWorkspacePRs(showTaskDetails ? s.activeWorkspaceId : null);
```
**Mirroring that expression for GitLab is a cross-surface data-loss bug.** The
two hooks do not have the same null behaviour: `useWorkspacePRs(null)` clears a
local ref and touches no store state, while `useWorkspaceMRs(null)` calls
`resetTaskMRs()` **with no argument**, which assigns `taskMRs.byWorkspaceId = {}`
— every workspace, wiped. `AppSidebar` is mounted in the root layout and is
therefore on screen on `/tasks`, so the gated form would blank the sidebar's MR
badges for the whole time a user sits on `/tasks` with task details off.
Add, unconditionally:
```ts
import { useWorkspaceMRs } from "@/hooks/domains/gitlab/use-task-mr";
// ...
useWorkspaceMRs(s.activeWorkspaceId);
```
matching `kanban-board.tsx:321`'s existing unconditional call rather than
`useWorkspacePRs`'s gated one. (AC12)
Passing `null` because `s.activeWorkspaceId` is itself `null` is permitted and
is not the forbidden case: with no active workspace `useTaskMRs` returns
`EMPTY_MRS` for every task, so the clear takes nothing away. (AC21)
**Check `max-lines` on this file before assuming the edit is free.** It measures
**597 effective lines of 600** — the tightest of the three, despite being the
smaller file by raw count (642 vs 660). The edit above is exactly two effective
lines, landing it at 599. That fits, but with one line to spare. If the actual
`eslint` run disagrees, the remedy is an extraction into a sibling under
`app/tasks/` (the spec's Constraints permit exactly one new file for this
purpose), **not** an `eslint-disable`: the file carries none today.
### API client
None.
### State
None. Reads go through the existing `useTaskMRs(taskId)`
(`hooks/domains/gitlab/use-task-mr.ts:60`), which resolves `workspaces.activeId`
itself and returns the module-level, referentially stable `EMPTY_MRS` when there
is nothing to show. No new selector may be introduced, and nothing added by this
feature may return a freshly allocated array or object — a fresh `[]` causes an
infinite re-render loop, as `EMPTY_MRS`' own comment records. (AC18)
`apps/web/components/gitlab/mr-task-icon.tsx` and everything under
`apps/web/components/github/` are consumed exactly as they ship and are not
modified. (AC14, AC15)
---
## Tests
Unit scenarios are `U1` to `U11` per the spec. Note the spec's numbering rule:
cite scenarios by prefixed id, never by bare number.
| # | What | File | How |
|---|---|---|---|
| U1 | Sidebar, PR and MR together, PR first in DOM order (AC2) | `components/task/task-item.test.tsx` | Render `TaskItem` under `StateProvider` with `initialState` seeding `taskPRs.byTaskId.t1`, `taskMRs.byWorkspaceId.ws1.t1`, `workspaces.activeId = "ws1"`; assert both testids present and `compareDocumentPosition` |
| U2 | Sidebar, MR only, no PR and no `prInfo` (AC3) | same | The case the early return makes impossible today |
| U3 | Sidebar, `prInfo` fallback plus MR, PR first (AC4) | same | `prInfo={{ number: 7, state: "Open" }}`, no store PR |
| U4 | Sidebar, no `taskId` (AC5) | same | **Two clauses, both required.** (a) no `mr-task-icon-*` element; (b) `MRTaskIcon` **not invoked at all** |
| U5 | Sidebar, no MRs, no `mr-task-icon-*` element (AC6) | same | PR only |
| U6 | `/tasks` row, contributions shown: both badges inside the single wrapper, PR first, wrapper carries `inline-flex items-center gap-1` (AC8, AC9, AC23) | `app/tasks/rich-task-list-row.test.tsx` (new) | Render the exported `TaskListRowPrimaryContent` with `showTaskDetails` true under `StateProvider`, following `tasks-list-view.test.tsx`'s no-mock shape |
| U7 | `/tasks` row, contributions hidden: neither badge (AC10) | same | Same store, compact path |
| U8 | `useWorkspaceMRs(null)` wipes every workspace (AC13) | `hooks/domains/gitlab/use-task-mr.test.ts` | Seed `byWorkspaceId["ws-a"]` and `["ws-b"]`, render the hook with `null`, assert both gone. Pins the existing behaviour AC12 exists to route around |
| U9 | `TasksPageClient` calls `useWorkspaceMRs` with the workspace id, not `null`, while `tasksListShowDetails` is false (AC12) | `app/tasks/tasks-page-client.mr-hydration.test.tsx` (new) | Mock `@/hooks/domains/gitlab/use-task-mr` with `vi.fn()`, assert the argument. See the risk note in task-03 |
| U10 | Sidebar, MR before the issue badge, run with a store PR present so it covers the full PR-MR-issue order (AC22) | `components/task/task-item.test.tsx` | `issueInfo={{ url, number: 42 }}` plus a seeded PR and MR |
| U11 | MR seeded but `workspaces.activeId = null`: no badge (AC21) | same | Observes AC21's second clause, which no other scenario reaches |
**U4 clause (b) needs a `vi.fn()`-backed component mock, and no in-repo
precedent exists — write it fresh.** `components/kanban-card-content.test.tsx` is
the precedent for **module-level interception only**: it replaces the module with
a plain stub (`MRTaskIcon: () => <span data-testid="mr-task-icon" />`), and a stub
records no calls, so clause (b) cannot be asserted against it. Copy that file's
`vi.mock` placement and factory shape; do **not** copy its stub body. The required
shape is:
```tsx
vi.mock("@/components/gitlab/mr-task-icon", () => ({ MRTaskIcon: vi.fn(() => null) }));
// ...
expect(MRTaskIcon).not.toHaveBeenCalled();
```
Clause (b) is the load-bearing one: an unguarded `<MRTaskIcon taskId={taskId!} />`
would pass clause (a) while breaking AC5.
---
## E2E Tests
Required: `apps/web/**` is touched and none of the files are on the Testing
step's exemption allowlist.
All GitLab scenarios seed through the GitLab mock provider and a task created
with **no agent**, for the reason `mr-task-card-badge.spec.ts`'s `seedBoardTask`
comment records: `createTaskWithAgent` auto-starts a session, the start step
carries `on_turn_complete: move_to_step review`, and the card leaves the column
mid-assertion.
**Seed helpers are copied, not imported.** `nextMRIID`, `seedMR`, `linkMR`,
`ensureGitLabConfigured` and `seedBoardTask` are file-local and **unexported** in
`mr-task-card-badge.spec.ts`. Each new spec defines its own local copies.
`mr-task-card-badge.spec.ts` is not edited to export them, which is what keeps
AC16 ("passes unmodified") literally true, and it matches the in-repo precedent:
`mobile-mr-task-card-badge.spec.ts` already writes its own `seedBoardTaskWithMR`.
Shared **constants** are different: import `GITLAB_HOST` and `GITLAB_PROJECT`
from `e2e/helpers/gitlab.ts`.
**Lint consequence the builder must respect.** The spec corrects an earlier draft
here, and the correct mechanism is narrower than it looks. In
`apps/web/eslint.config.mjs`, `sonarjs/no-identical-functions` sits in the global
block (no `files`, no `ignores`), so it **is live on `e2e/**`** — the
`e2e/**` entry in an `ignores` array belongs to the i18n guard block, and the
`files: ["e2e/**/*.ts"]` override disables `max-lines` and
`sonarjs/no-duplicate-string` but **not** `no-identical-functions`. It cannot fire
across files, because ESLint sees one file at a time. So: copy each helper
across files freely; **never write two copies of the same helper inside one
file**, because `pnpm --filter @kandev/web lint` runs `eslint --max-warnings 0`.
**The mock GitHub PR for E3, E6 and E7** comes from the existing mock-GitHub API
client methods: `apiClient.mockGitHubReset()`, `apiClient.mockGitHubSetUser()`,
then `apiClient.mockGitHubAssociateTaskPR({ task_id, owner, repo, pr_number,
pr_url, pr_title, head_branch, base_branch, author_login, state })` — `state` is
optional and is passed explicitly. **`mockGitHubAddPRs()` is the wrong call and
must not be used**: it seeds the mock provider's PR *catalogue* and creates no
task-to-PR association, so `taskPRs.byTaskId[taskId]` stays empty, `PRTaskIcon`
renders nothing, and the PR-before-MR assertion can never run. The reference is
`mr-task-card-badge.spec.ts`'s own `"AC30/AC37"` test; reading it does not modify
it.
**Every `mr-task-icon-*` accessor must be container-scoped** and may not use
`.first()`. One task id can be emitted by two mounted rows on one route (sidebar
plus board, or sidebar plus `/tasks` row). Scope to `app-sidebar`,
`tasks-list-row`, or `task-card-<id>`. (AC19)
`apps/web/e2e/tests/gitlab/mr-sidebar-badge.spec.ts` (new):
- **E1** — On `/` (the board mounts the hydration owner), a task with one linked
open MR: inside `app-sidebar`, row located by `[data-task-row-id="<taskId>"]`,
`mr-task-icon-<taskId>` visible with `data-mr-count="1"` and
`data-mr-state="open"`. (AC1, AC19)
- **E2** — Same route, task with no linked MR: inside `app-sidebar`,
`mr-task-icon-<taskId>` has count 0. (AC6)
- **E3** — Task with both a mock GitHub PR and a linked MR: inside the sidebar
row, both visible, PR precedes MR by `compareDocumentPosition`. (AC2)
`apps/web/e2e/tests/gitlab/mr-tasks-list-badge.spec.ts` (new):
- **E4** — Navigate to `/tasks`, enable "Show task details" through the
`display-button` menu (the pattern in `task-listing-view-preferences.spec.ts`:
`getByTestId("display-button").click()` then
`getByText("Show task details", { exact: true }).click()`), locate the
`tasks-list-row` by title (the row carries **no task-id attribute**; only
`tasks-list-row-title` identifies it), assert `mr-task-icon-<taskId>` inside
that row. (AC8, AC19)
- **E5** — Same task, details off: inside the row, both `pr-task-icon-<taskId>`
and `mr-task-icon-<taskId>` have count 0. (AC10)
- **E6** — Task with both: inside the row, PR precedes MR. (AC9)
`apps/web/e2e/tests/gitlab/mobile-mr-tasks-list-badge.spec.ts` (new):
- **E7** — Mobile viewport, details on, task with both badges: the MR badge is
visible and `assertNoDocumentHorizontalOverflow` passes. Mirrors
`mobile-mr-task-card-badge.spec.ts`. (AC20)
All seven scenarios run on `/` or `/tasks`. Neither route mounts
`TaskPageContent`, so none is exposed to the two accepted hydration holes the
spec records (an archived task at `/t/:taskId`, and
`use-external-vcs-file-link.ts`'s already-shipped gated `useWorkspaceMRs(null)`).
The builder must not attempt to work around either hole from the three production
files in scope; in particular the sidebar must not gain its own `useWorkspaceMRs`
call, which AC7 forbids.
**Page object.** Extend `e2e/pages/app-sidebar-page.ts` (already anchored at
`app-sidebar`) with a row-and-badge accessor. Do not add a parallel sidebar page
object; `e2e/pages/sidebar-tasks-page.ts` is the shape to follow.
---
## Verification Results
Pending. On completion, synchronize this section with each task's `## Results`:
record exact commands and outcomes/counts, generated artifact paths, and
cleanup/teardown evidence.
---
## Implementation Waves And Parallel Candidates
The three production tasks touch disjoint files and share no schema, migration,
generated contract, lockfile, or package-wide config, so they are genuine
parallel candidates. **The default is sequential execution in the primary
conversation.** Waves do not authorize subagents; only the user may ask for them
after selecting the implementation model.
```
Wave 1 (parallel candidates — user authorization required):
- [ ] [task-01-sidebar-mr-badge](task-01-sidebar-mr-badge.md)
- [ ] [task-02-tasks-row-mr-badge](task-02-tasks-row-mr-badge.md)
- [ ] [task-03-tasks-page-mr-hydration](task-03-tasks-page-mr-hydration.md)
Wave 2:
- [ ] [task-04-e2e-sidebar-badge](task-04-e2e-sidebar-badge.md) (needs 01)
- [ ] [task-05-e2e-tasks-list-badge](task-05-e2e-tasks-list-badge.md) (needs 02, 03)
```
Before any task, in a fresh worktree: `cd apps && pnpm install --frozen-lockfile`.
`apps/node_modules/` is not shared across worktrees, and without it `vitest`,
`eslint` and the commit hooks all fail.
---
## Open Questions
None. The spec settles badge ordering (PR then MR, DOM order, all three
surfaces), the `/tasks` flag question (one flag, renamed `showContributions`),
coarse-pointer behaviour (the Radix tooltip is inherited unchanged), and the
sidebar `prInfo` question (deliberately GitHub-only; an MR analogue is a backend
projection change and is out of scope).