@dxos/plugin-github 0.7.4 → 0.14.0

package/src/containers/PullRequestCardMenu/PullRequestCardMenu.tsx

@@ -0,0 +1,134 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useCallback, useMemo } from 'react';
+
+import * as Hooks from '@dxos/app-framework/Hooks';
+import type * as AppSurface from '@dxos/app-toolkit/AppSurface';
+import * as ToolkitHooks from '@dxos/app-toolkit/Hooks';
+import * as LayoutOperation from '@dxos/app-toolkit/LayoutOperation';
+import { Filter, Obj, Ref } from '@dxos/echo';
+import { useQuery } from '@dxos/echo-react';
+import { log } from '@dxos/log';
+import { createMenuAction, useMenuContribution } from '@dxos/react-ui-menu';
+import * as UiHooks from '@dxos/react-ui/Hooks';
+import { PullRequest } from '@dxos/types';
+
+import { meta } from '#meta';
+import { GitHubOperation, Walkthrough } from '#types';
+
+import { useOpenObject } from '../../hooks/index.ts';
+import { newestWalkthrough } from '../../walkthrough/index.ts';
+
+const WALKTHROUGH_ICON = 'ph--path--regular';
+
+export type PullRequestCardMenuProps = AppSurface.CardMenuData<PullRequest.PullRequest>;
+
+/**
+ * Adds "Open walkthrough" or "Generate walkthrough" to a pull request card's menu, whichever applies.
+ *
+ * Either way what opens is the pull request: the walkthrough is what its article renders, so a
+ * generation that is still running does not leave the reader with nothing to open. A preview card
+ * holds a pull request minted in memory from its URL, so the stored copy with the same
+ * owner/repo/number is what the menu acts on — in the pull request's own space when it has one,
+ * otherwise the space the user is working in.
+ */
+export const PullRequestCardMenu = ({ subject, menu }: PullRequestCardMenuProps) => {
+  const { t } = UiHooks.useTranslation(meta.profile.key);
+  const { invokePromise } = Hooks.useOperationInvoker();
+  const openObject = useOpenObject();
+  const activeSpace = ToolkitHooks.useActiveSpace();
+  const db = Obj.getDatabase(subject) ?? activeSpace?.db;
+  const { owner, repo, number } = subject;
+
+  const [stored] = useQuery(db, Filter.type(PullRequest.PullRequest, { owner, repo, number }));
+  const walkthroughs = useQuery(
+    db,
+    stored ? Filter.type(Walkthrough.Walkthrough, { pullRequest: Ref.make(stored) }) : Filter.nothing(),
+  );
+  const walkthrough = useMemo(() => newestWalkthrough(walkthroughs), [walkthroughs]);
+
+  const generateWalkthrough = useCallback(async () => {
+    if (!db) {
+      return;
+    }
+    const pullRequest = stored ?? db.add(PullRequest.make(toStoredFields(subject)));
+    const reference = PullRequest.reference(pullRequest);
+    const toastId = `${meta.profile.key}.walkthrough.${pullRequest.id}`;
+    const { data, error } = await invokePromise(
+      GitHubOperation.GenerateWalkthrough,
+      { pullRequest: Ref.make(pullRequest) },
+      { spaceId: db.spaceId },
+    );
+    if (error || !data?.walkthrough.target) {
+      log.warn('walkthrough generation failed', { reference, error });
+      await invokePromise(LayoutOperation.AddToast, {
+        id: toastId,
+        icon: 'ph--warning--regular',
+        title: ['walkthrough-failed.title', { ns: meta.profile.key }],
+        description: reference,
+      });
+      return;
+    }
+    await invokePromise(LayoutOperation.AddToast, {
+      id: toastId,
+      icon: WALKTHROUGH_ICON,
+      title: ['walkthrough-ready.title', { ns: meta.profile.key }],
+      description: reference,
+      actionLabel: ['open-walkthrough.label', { ns: meta.profile.key }],
+      actionAlt: ['open-walkthrough.label', { ns: meta.profile.key }],
+      onAction: () => void openObject(pullRequest),
+    });
+  }, [db, stored, subject, invokePromise, openObject]);
+
+  const items = useMemo(() => {
+    if (!db) {
+      return [];
+    }
+    return [
+      walkthrough && stored
+        ? createMenuAction('open-walkthrough', () => void openObject(stored), {
+            label: t('open-walkthrough.label'),
+            icon: WALKTHROUGH_ICON,
+          })
+        : createMenuAction('generate-walkthrough', () => void generateWalkthrough(), {
+            label: t('generate-walkthrough.label'),
+            icon: WALKTHROUGH_ICON,
+          }),
+    ];
+  }, [db, stored, walkthrough, openObject, generateWalkthrough, t]);
+
+  useMenuContribution(menu, { id: `${meta.profile.key}.walkthrough`, mode: 'additive', items });
+
+  return null;
+};
+
+/** The fields of an in-memory pull request, copied into a new object the space can store. */
+const toStoredFields = ({
+  owner,
+  repo,
+  number,
+  title,
+  url,
+  state,
+  author,
+  description,
+  baseBranch,
+  headBranch,
+  additions,
+  deletions,
+}: PullRequest.PullRequest): Obj.MakeProps<typeof PullRequest.PullRequest> => ({
+  owner,
+  repo,
+  number,
+  title,
+  url,
+  state,
+  author,
+  description,
+  baseBranch,
+  headBranch,
+  additions,
+  deletions,
+});

package/src/containers/PullRequestCardMenu/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { PullRequestCardMenu as default } from './PullRequestCardMenu.tsx';

package/src/containers/PullRequestsArticle/PullRequestsArticle.tsx

@@ -0,0 +1,361 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { useAtomValue } from '@effect/atom-react/Hooks';
+import * as Atom from 'effect/reactivity/Atom';
+import React, { useCallback, useMemo, useRef } from 'react';
+
+import { type Database, Filter, Obj, Tag, Type } from '@dxos/echo';
+import { QueryBuilder } from '@dxos/echo-query';
+import { useQuery } from '@dxos/echo-react';
+import { useAttention, useViewState, useViewStateActions } from '@dxos/react-ui-attention';
+import { type EditorController } from '@dxos/react-ui-editor';
+import { Listbox } from '@dxos/react-ui-list';
+import { GroupMenu, SortMenu } from '@dxos/react-ui-menu';
+import { QueryEditor, usePersistentQuery } from '@dxos/react-ui-query';
+import * as Button from '@dxos/react-ui/Button';
+import * as UiHooks from '@dxos/react-ui/Hooks';
+import * as Icon from '@dxos/react-ui/Icon';
+import * as Layout from '@dxos/react-ui/Layout';
+import * as Panel from '@dxos/react-ui/Panel';
+import * as Status from '@dxos/react-ui/Status';
+import * as Toolbar from '@dxos/react-ui/Toolbar';
+import { PullRequest, Task } from '@dxos/types';
+
+import { meta } from '#meta';
+
+import { useOpenObject, usePullRequestChecks } from '../../hooks/index.ts';
+import * as PullRequestsView from '../../types/PullRequestsView.ts';
+import {
+  CI_HUE,
+  type PullRequestChecks,
+  type PullRequestRow,
+  type PullRequestRowGroup,
+  STATE_HUE,
+  filterRows,
+  groupRows,
+  sortRows,
+} from './arrange.ts';
+import { formatRelative } from './format.ts';
+
+const PULL_REQUEST_TYPENAME = Type.getTypename(PullRequest.PullRequest);
+
+const SORT_ICONS: Record<PullRequestsView.SortField, string> = {
+  relevance: 'ph--lightning--regular',
+  updated: 'ph--clock-clockwise--regular',
+  created: 'ph--calendar-plus--regular',
+  number: 'ph--hash--regular',
+  title: 'ph--text-aa--regular',
+};
+
+const GROUP_ICONS: Record<PullRequestsView.GroupField, string> = {
+  none: 'ph--list--regular',
+  repo: 'ph--git-branch--regular',
+  state: 'ph--git-pull-request--regular',
+  checks: 'ph--check-circle--regular',
+  author: 'ph--user--regular',
+};
+
+export type PullRequestsArticleProps = {
+  role?: string;
+  attendableId: string;
+  /** The space's database; absent when the type node carries no space, which renders nothing. */
+  db?: Database.Database;
+};
+
+/**
+ * Every pull request in a space as one list a reader triages from: repository, title, CI checks,
+ * the tasks that track it and its state, ordered by relevance (what needs the reader first) or time.
+ * The filter, order and grouping persist per device and per space, through the same view-state
+ * aspect, query editor and sort/group menus a task set's list uses.
+ */
+export const PullRequestsArticle = ({ db, ...props }: PullRequestsArticleProps) =>
+  db ? <PullRequestList db={db} {...props} /> : null;
+
+PullRequestsArticle.displayName = 'PullRequestsArticle';
+
+const PullRequestList = ({ role, attendableId, db }: PullRequestsArticleProps & { db: Database.Database }) => {
+  const { t } = UiHooks.useTranslation(meta.profile.key);
+  const { hasAttention } = useAttention(attendableId);
+  const editorRef = useRef<EditorController>(null);
+  const contextId = db.spaceId;
+
+  const [query, setQuery] = usePersistentQuery(PullRequestsView.aspect, contextId, editorRef);
+  const { sort = PullRequestsView.DEFAULT_SORT, group = 'none' } = useViewState(PullRequestsView.aspect, contextId);
+  const { update } = useViewStateActions(PullRequestsView.aspect, contextId);
+  const handleSortChange = useCallback(
+    (sort: PullRequestsView.Sort) => update((view) => ({ ...view, sort })),
+    [update],
+  );
+  const handleGroupChange = useCallback(
+    (group: PullRequestsView.GroupField) => update((view) => ({ ...view, group })),
+    [update],
+  );
+  const handleClear = useCallback(() => setQuery(''), [setQuery]);
+
+  const tags = useTagMap(db);
+  // A query that does not parse matches nothing rather than everything.
+  const filter = useMemo(() => {
+    const text = query.trim();
+    return text.length === 0 ? undefined : (new QueryBuilder(tags).build(text).filter ?? Filter.nothing());
+  }, [query, tags]);
+
+  const pullRequests = useQuery(db, Filter.type(PullRequest.PullRequest));
+  const tasks = useQuery(db, Filter.type(Task.Task));
+  const checks = usePullRequestChecks(pullRequests, db.spaceId);
+  const { rows, groups } = useArrangedRows(pullRequests, tasks, checks, { filter, sort, group });
+  // In display order, so keyboard order follows the groups the reader sees.
+  const options = useMemo(
+    () =>
+      (groups ? groups.flatMap((group) => group.rows) : rows).map(({ pullRequest }) => ({
+        value: pullRequest.id,
+        label: pullRequest.title,
+      })),
+    [groups, rows],
+  );
+
+  const sortFields = useMemo(
+    () =>
+      PullRequestsView.SortField.literals.map((id) => ({
+        id,
+        label: t(`pull-requests-sort-${id}.label`),
+        icon: SORT_ICONS[id],
+      })),
+    [t],
+  );
+  const directionLabels = useMemo(
+    () => ({ asc: t('pull-requests-sort-asc.label'), desc: t('pull-requests-sort-desc.label') }),
+    [t],
+  );
+  const groupFields = useMemo(
+    () =>
+      PullRequestsView.GroupField.literals.map((id) => ({
+        id,
+        label: t(`pull-requests-group-${id}.label`),
+        icon: GROUP_ICONS[id],
+      })),
+    [t],
+  );
+
+  const openObject = useOpenObject();
+
+  return (
+    <Panel.Root role={role} data-testid='pull-requests'>
+      <Panel.Header>
+        <Toolbar.Root inactive={!hasAttention}>
+          <QueryEditor
+            classNames='grow min-w-0 ps-1'
+            db={db}
+            tags={tags}
+            value={query}
+            onChange={setQuery}
+            ref={editorRef}
+          />
+          <SortMenu
+            fields={sortFields}
+            value={sort}
+            onChange={handleSortChange}
+            label={t('pull-requests-sort.label')}
+            directionLabels={directionLabels}
+            testId='pull-requests.sort'
+          />
+          <GroupMenu
+            fields={groupFields}
+            value={group}
+            onChange={handleGroupChange}
+            label={t('pull-requests-group.label')}
+            none='none'
+            testId='pull-requests.group'
+          />
+          <Button.Root
+            icon='ph--x--regular'
+            iconOnly
+            disabled={query.trim().length === 0}
+            label={t('pull-requests-filter-clear.label')}
+            data-testid='pull-requests.filter.clear'
+            onClick={handleClear}
+          />
+        </Toolbar.Root>
+      </Panel.Header>
+      <Panel.Body>
+        {rows.length === 0 ? (
+          <Status.Empty classNames='dx-expand'>
+            {t(pullRequests.length === 0 ? 'pull-requests-empty.message' : 'pull-requests-no-match.message')}
+          </Status.Empty>
+        ) : (
+          <Listbox.Root items={options}>
+            <Listbox.Content
+              classNames='dx-expand'
+              aria-label={t('typename.label_other', { ns: PULL_REQUEST_TYPENAME })}
+            >
+              {groups
+                ? groups
+                    .filter((group) => group.rows.length > 0)
+                    .map((group) => <GroupSection key={group.id} group={group} onOpen={openObject} />)
+                : rows.map((row) => <PullRequestListRow key={row.pullRequest.id} row={row} onOpen={openObject} />)}
+            </Listbox.Content>
+          </Listbox.Root>
+        )}
+      </Panel.Body>
+    </Panel.Root>
+  );
+};
+
+type OpenHandler = (object: Obj.Any) => Promise<void>;
+
+const GroupSection = ({ group, onOpen }: { group: PullRequestRowGroup; onOpen: OpenHandler }) => {
+  const { t } = UiHooks.useTranslation(meta.profile.key);
+  return (
+    <Listbox.ItemGroup>
+      <Listbox.ItemGroupLabel>
+        <Layout.Flex align='center' gap='sm'>
+          <Icon.Icon icon={group.icon} classNames='dx-text' data-hue={group.hue} />
+          <span className='truncate'>{group.translate ? t(group.label) : group.label}</span>
+          <span className='text-description'>{group.rows.length}</span>
+        </Layout.Flex>
+      </Listbox.ItemGroupLabel>
+      {group.rows.map((row) => (
+        <PullRequestListRow key={row.pullRequest.id} row={row} onOpen={onOpen} />
+      ))}
+    </Listbox.ItemGroup>
+  );
+};
+
+/** One pull request: its repository and number, title, author and time, then checks, tasks and state. */
+const PullRequestListRow = ({
+  row: { pullRequest, checks, tasks },
+  onOpen,
+}: {
+  row: PullRequestRow;
+  onOpen: OpenHandler;
+}) => {
+  const { t } = UiHooks.useTranslation(meta.profile.key);
+  const time = pullRequest.updatedAt ?? pullRequest.createdAt;
+  return (
+    <Listbox.Item
+      id={pullRequest.id}
+      classNames='cursor-pointer py-2'
+      data-testid='pull-requests.row'
+      onClick={() => void onOpen(pullRequest)}
+    >
+      <Layout.Flex column gap='xs' grow>
+        <Layout.Flex align='center' gap='sm' classNames='min-w-0'>
+          <span className='dx-tag dx-tag-inline shrink-0' data-hue='neutral'>
+            {PullRequest.reference(pullRequest)}
+          </span>
+          <span className='truncate grow'>{pullRequest.title}</span>
+          <ChecksTag pullRequest={pullRequest} checks={checks} />
+          <span
+            className='dx-tag dx-tag-inline shrink-0'
+            data-hue={STATE_HUE[pullRequest.state]}
+            data-testid='pull-requests.row.state'
+          >
+            {t(`pull-request-state.${pullRequest.state}.label`)}
+          </span>
+        </Layout.Flex>
+        <Layout.Flex align='center' gap='sm' classNames='min-w-0 text-xs text-description'>
+          {pullRequest.author && <span className='shrink-0'>{pullRequest.author}</span>}
+          {time && (
+            <time className='shrink-0' dateTime={time} title={new Date(time).toLocaleString()}>
+              {formatRelative(time)}
+            </time>
+          )}
+          {tasks.length > 0 && (
+            <Layout.Flex align='center' gap='xs' classNames='min-w-0' data-testid='pull-requests.row.tasks'>
+              <Icon.Icon icon='ph--check-square-offset--regular' size='xs' classNames='shrink-0' />
+              <span className='truncate'>{tasks.map((task) => task.title || t('untitled-task.label')).join(', ')}</span>
+            </Layout.Flex>
+          )}
+        </Layout.Flex>
+      </Layout.Flex>
+    </Listbox.Item>
+  );
+};
+
+const ChecksTag = ({ pullRequest, checks }: { pullRequest: PullRequest.PullRequest; checks?: PullRequestChecks }) => {
+  const { t } = UiHooks.useTranslation(meta.profile.key);
+  // A finished pull request's checks are not read (see `usePullRequestChecks`), so it shows none.
+  if (!checks) {
+    return pullRequest.state === 'open' || pullRequest.state === 'draft' ? (
+      <span className='dx-tag dx-tag-inline' data-hue='neutral' data-testid='pull-requests.row.checks'>
+        {t('ci-status.unknown.label')}
+      </span>
+    ) : null;
+  }
+
+  return (
+    <>
+      {checks.review !== 'none' && (
+        <span
+          className='dx-tag dx-tag-inline'
+          data-hue={checks.review === 'approved' ? 'green' : 'red'}
+          data-testid='pull-requests.row.review'
+        >
+          {t(`review-status.${checks.review}.label`, { count: checks.approvals })}
+        </span>
+      )}
+      <span className='dx-tag dx-tag-inline' data-hue={CI_HUE[checks.ci]} data-testid='pull-requests.row.checks'>
+        {t(`ci-status.${checks.ci}.label`)}
+        {checks.checks.total > 0 && ` ${checks.checks.passed}/${checks.checks.total}`}
+      </span>
+    </>
+  );
+};
+
+type ArrangeOptions = {
+  filter: Filter.Any | undefined;
+  sort: PullRequestsView.Sort;
+  group: PullRequestsView.GroupField;
+};
+
+/**
+ * The rows the toolbar keeps, in the order it asks for, partitioned into its groups. Read through
+ * atoms so a re-sync (a new state, a new title) or a task gaining the pull request as an artifact
+ * re-arranges the list without the queries re-emitting.
+ */
+const useArrangedRows = (
+  pullRequests: readonly PullRequest.PullRequest[],
+  tasks: readonly Task.Task[],
+  checks: ReadonlyMap<string, PullRequestChecks>,
+  { filter, sort, group }: ArrangeOptions,
+): { rows: readonly PullRequestRow[]; groups?: PullRequestRowGroup[] } => {
+  const atom = useMemo(
+    () =>
+      Atom.make((get) => {
+        pullRequests.forEach((pullRequest) => get(Obj.atom(pullRequest)));
+        const tasksByPullRequest = new Map<string, Task.Task[]>();
+        for (const task of tasks) {
+          for (const ref of get(Obj.atomProperty(task, 'artifacts')) ?? []) {
+            const id = Task.refEntityId(ref);
+            if (id) {
+              tasksByPullRequest.set(id, [...(tasksByPullRequest.get(id) ?? []), task]);
+            }
+          }
+        }
+        const all = pullRequests.map((pullRequest) => ({
+          pullRequest,
+          checks: checks.get(pullRequest.id),
+          tasks: tasksByPullRequest.get(pullRequest.id) ?? [],
+        }));
+        const rows = sortRows(filterRows(all, filter), sort);
+        return { rows, groups: groupRows(rows, group) };
+      }),
+    [pullRequests, tasks, checks, filter, sort, group],
+  );
+
+  return useAtomValue(atom);
+};
+
+/** Tag registry keyed by the `Tag` object's uri — the id space `#tag` terms and `meta.tags` share. */
+const useTagMap = (db: Database.Database): Tag.Map => {
+  const tags = useQuery(db, Filter.type(Tag.Tag));
+  return useMemo(
+    () =>
+      tags.reduce<Tag.Map>((acc, tag) => {
+        acc[Obj.getURI(tag).toString()] = tag;
+        return acc;
+      }, {}),
+    [tags],
+  );
+};

package/src/containers/PullRequestsArticle/arrange.test.ts

@@ -0,0 +1,122 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { QueryBuilder } from '@dxos/echo-query';
+import { PullRequest, Task } from '@dxos/types';
+
+import { type PullRequestChecks, type PullRequestRow, filterRows, groupRows, relevance, sortRows } from './arrange.ts';
+import { formatRelative } from './format.ts';
+
+const make = (
+  number: number,
+  props: Partial<Pick<PullRequest.PullRequest, 'state' | 'repo' | 'author' | 'title' | 'updatedAt' | 'createdAt'>> = {},
+): PullRequest.PullRequest =>
+  PullRequest.make({ owner: 'dxos', repo: 'dxos', number, title: `Change ${number}`, state: 'open', ...props });
+
+const checks = (ci: PullRequestChecks['ci'], review: PullRequestChecks['review'] = 'none'): PullRequestChecks => ({
+  ci,
+  review,
+  approvals: review === 'approved' ? 1 : 0,
+  checks: { total: 1, passed: ci === 'success' ? 1 : 0, failed: ci === 'failure' ? 1 : 0, pending: 0 },
+});
+
+const row = (pullRequest: PullRequest.PullRequest, extra: Partial<Omit<PullRequestRow, 'pullRequest'>> = {}) => ({
+  pullRequest,
+  tasks: [],
+  ...extra,
+});
+
+const numbers = (rows: readonly PullRequestRow[]) => rows.map(({ pullRequest }) => pullRequest.number);
+
+describe('relevance', () => {
+  test('an open pull request with something to fix outranks one ready to merge, then one waiting', ({ expect }) => {
+    const failing = row(make(1), { checks: checks('failure') });
+    const ready = row(make(2), { checks: checks('success', 'approved') });
+    const waiting = row(make(3), { checks: checks('success') });
+    const merged = row(make(4, { state: 'merged' }));
+    expect(relevance(failing)).toBeGreaterThan(relevance(ready));
+    expect(relevance(ready)).toBeGreaterThan(relevance(waiting));
+    expect(relevance(waiting)).toBeGreaterThan(relevance(merged));
+  });
+
+  test('a pull request a task tracks is nudged above an otherwise equal one', ({ expect }) => {
+    const task = Task.make({ title: 'Ship it' });
+    expect(relevance(row(make(1), { tasks: [task] }))).toBeGreaterThan(relevance(row(make(2))));
+  });
+});
+
+describe('sortRows', () => {
+  test('relevance descending puts the most urgent first and breaks ties by recency', ({ expect }) => {
+    const rows = [
+      row(make(1, { state: 'closed' })),
+      row(make(2, { updatedAt: '2026-09-01T00:00:00Z' })),
+      row(make(3, { updatedAt: '2026-10-01T00:00:00Z' })),
+      row(make(4), { checks: checks('failure') }),
+    ];
+    expect(numbers(sortRows(rows, { field: 'relevance', direction: 'desc' }))).toEqual([4, 3, 2, 1]);
+  });
+
+  test('updated falls back to when it was opened', ({ expect }) => {
+    const rows = [
+      row(make(1, { updatedAt: '2026-01-01T00:00:00Z' })),
+      row(make(2, { createdAt: '2026-06-01T00:00:00Z' })),
+    ];
+    expect(numbers(sortRows(rows, { field: 'updated', direction: 'desc' }))).toEqual([2, 1]);
+  });
+});
+
+describe('groupRows', () => {
+  test('none leaves the list ungrouped', ({ expect }) => {
+    expect(groupRows([row(make(1))], 'none')).toBeUndefined();
+  });
+
+  test('state groups come in lifecycle order and keep the sort within each', ({ expect }) => {
+    const rows = [row(make(1, { state: 'merged' })), row(make(3)), row(make(2))];
+    const groups = groupRows(rows, 'state') ?? [];
+    expect(groups.map((group) => group.id)).toEqual(['state-open', 'state-merged']);
+    expect(numbers(groups[0].rows)).toEqual([3, 2]);
+  });
+
+  test('checks put failures first and rows without checks last', ({ expect }) => {
+    const rows = [
+      row(make(1)),
+      row(make(2), { checks: checks('success') }),
+      row(make(3), { checks: checks('failure') }),
+    ];
+    expect((groupRows(rows, 'checks') ?? []).map((group) => group.id)).toEqual([
+      'checks-failure',
+      'checks-success',
+      'checks-unknown',
+    ]);
+  });
+
+  test('repositories are grouped by owner and name', ({ expect }) => {
+    const rows = [row(make(1, { repo: 'edge' })), row(make(2)), row(make(3, { repo: 'edge' }))];
+    const groups = groupRows(rows, 'repo') ?? [];
+    expect(groups.map((group) => [group.label, numbers(group.rows)])).toEqual([
+      ['dxos/dxos', [2]],
+      ['dxos/edge', [1, 3]],
+    ]);
+  });
+});
+
+describe('filterRows', () => {
+  test('free text searches the title, reference and author', ({ expect }) => {
+    const rows = [row(make(1, { title: 'Fix sync' })), row(make(2, { author: 'burdon' })), row(make(3))];
+    const build = (text: string) => new QueryBuilder().build(text).filter;
+    expect(numbers(filterRows(rows, build('sync')))).toEqual([1]);
+    expect(numbers(filterRows(rows, build('burdon')))).toEqual([2]);
+    expect(numbers(filterRows(rows, undefined))).toEqual([1, 2, 3]);
+  });
+});
+
+describe('formatRelative', () => {
+  test('uses the largest unit that fits', ({ expect }) => {
+    const now = Date.parse('2026-10-07T12:00:00Z');
+    expect(formatRelative('2026-10-07T09:00:00Z', now)).toMatch(/3 hours ago/);
+    expect(formatRelative('not a date', now)).toEqual('');
+  });
+});