@dxos/plugin-github 0.7.4 → 0.14.0

package/src/components/PullRequestFiles/files.test.ts

@@ -0,0 +1,59 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { parsePatch } from '../../walkthrough/patch.ts';
+import { buildFileTree, diffFence, fileSignature, flattenFiles } from './files.ts';
+
+const patch = (path: string, line: string) =>
+  [`diff --git a/${path} b/${path}`, `--- a/${path}`, `+++ b/${path}`, '@@ -1,1 +1,1 @@', '-old', `+${line}`].join(
+    '\n',
+  );
+
+describe('buildFileTree', () => {
+  test('folds single-child directories and lists directories before files', ({ expect }) => {
+    const files = parsePatch(
+      [
+        patch('packages/core/echo/src/Filter.ts', 'a'),
+        patch('packages/core/echo/src/Query.ts', 'b'),
+        patch('packages/core/echo/package.json', 'c'),
+        patch('README.md', 'd'),
+      ].join('\n'),
+    );
+    const tree = buildFileTree(files);
+    expect(tree.children.map((node) => node.name)).toEqual(['packages/core/echo', 'README.md']);
+    expect(tree.children[0].children.map((node) => node.name)).toEqual(['src', 'package.json']);
+    expect(tree.children[0].added).toBe(3);
+    expect(flattenFiles(tree).map((file) => file.path)).toEqual([
+      'packages/core/echo/src/Filter.ts',
+      'packages/core/echo/src/Query.ts',
+      'packages/core/echo/package.json',
+      'README.md',
+    ]);
+  });
+});
+
+describe('buildFileTree, replaced paths', () => {
+  test('keeps a directory that replaced a file of the same name', ({ expect }) => {
+    const files = parsePatch([patch('docs/a', 'x'), patch('docs/a/b.md', 'y')].join('\n'));
+    expect(flattenFiles(buildFileTree(files)).map((file) => file.path)).toEqual(['docs/a/b.md', 'docs/a']);
+  });
+});
+
+describe('diffFence', () => {
+  test('outgrows any backtick run in the body', ({ expect }) => {
+    const [file] = parsePatch(patch('docs/README.md', '````ts'));
+    expect(diffFence(file).startsWith('`````diff file=docs/README.md\n@@ -1,1 +1,1 @@')).toBe(true);
+  });
+});
+
+describe('fileSignature', () => {
+  test('moves when the change does', ({ expect }) => {
+    const [first] = parsePatch(patch('a.ts', 'one'));
+    const [second] = parsePatch(patch('a.ts', 'two'));
+    expect(fileSignature(first)).toBe(fileSignature(parsePatch(patch('a.ts', 'one'))[0]));
+    expect(fileSignature(first)).not.toBe(fileSignature(second));
+  });
+});

package/src/components/PullRequestFiles/files.ts

@@ -0,0 +1,115 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type PatchFile, renderHunks } from '../../walkthrough/patch.ts';
+
+/** A node of the changed-file tree: a directory (with children) or a changed file (with its patch). */
+export type FileNode = {
+  /**
+   * A generated id rather than the path: the tree joins ids into row paths with a separator a file
+   * name may itself contain (`+page.svelte`).
+   */
+  id: string;
+  /** The full path of the file or directory; the synthetic root's is empty. */
+  path: string;
+  /** What the row shows: a base name, or a run of directories that each hold only one child. */
+  name: string;
+  file?: PatchFile;
+  children: FileNode[];
+  added: number;
+  removed: number;
+};
+
+/** Id of the synthetic root the tree model anchors its top-level rows to; never rendered. */
+export const FILE_TREE_ROOT = 'root';
+
+/**
+ * The changed files as a directory tree, directories before files and each alphabetical — the order
+ * GitHub's own file tree uses. A directory whose only child is another directory is folded into one
+ * row (`src/components`), since a chain of single-entry folders is depth without information.
+ */
+export const buildFileTree = (files: readonly PatchFile[]): FileNode => {
+  let count = 0;
+  const nextId = () => `node-${++count}`;
+  const root: FileNode = { id: FILE_TREE_ROOT, path: '', name: '', children: [], added: 0, removed: 0 };
+  for (const file of files) {
+    const segments = file.path.split('/');
+    let parent = root;
+    for (let index = 0; index < segments.length - 1; index++) {
+      const path = segments.slice(0, index + 1).join('/');
+      // Directories only: a change can replace a file with a directory of the same name.
+      let directory = parent.children.find((child) => !child.file && child.path === path);
+      if (!directory) {
+        directory = { id: nextId(), path, name: segments[index], children: [], added: 0, removed: 0 };
+        parent.children.push(directory);
+      }
+      parent = directory;
+    }
+    parent.children.push({
+      id: nextId(),
+      path: file.path,
+      name: segments.at(-1) ?? file.path,
+      file,
+      children: [],
+      added: file.added,
+      removed: file.removed,
+    });
+  }
+
+  const finish = (node: FileNode): FileNode => {
+    const children = node.children.map(finish).sort(compareNodes);
+    let folded: FileNode = {
+      ...node,
+      children,
+      added: node.file ? node.added : children.reduce((sum, child) => sum + child.added, 0),
+      removed: node.file ? node.removed : children.reduce((sum, child) => sum + child.removed, 0),
+    };
+    while (folded !== root && !folded.file && folded.children.length === 1 && !folded.children[0].file) {
+      const [only] = folded.children;
+      folded = { ...only, name: `${folded.name}/${only.name}` };
+    }
+    return folded;
+  };
+
+  return finish(root);
+};
+
+const compareNodes = (left: FileNode, right: FileNode): number =>
+  Number(!!left.file) - Number(!!right.file) || left.name.localeCompare(right.name);
+
+/** The files in the order the tree lists them, which is the order previous/next walks. */
+export const flattenFiles = (node: FileNode): PatchFile[] =>
+  node.file ? [node.file] : node.children.flatMap(flattenFiles);
+
+/**
+ * One file's change as the ```diff fence the walkthrough renders, so the files view shows a file
+ * exactly as a walkthrough chunk would. The fence is one backtick longer than any run in the body:
+ * a context line of a markdown file can itself be a fence, which would otherwise close this one.
+ */
+export const diffFence = (file: PatchFile): string => {
+  const body = renderHunks(file.hunks);
+  const longest = Math.max(0, ...(body.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = '`'.repeat(Math.max(3, longest + 1));
+  return `${fence}diff file=${file.path}\n${body}\n${fence}`;
+};
+
+/**
+ * A short digest of a file's change. A file is reviewed at a signature: when a push changes the
+ * file its signature moves and the check falls away, as GitHub's "Viewed" does.
+ */
+export const fileSignature = (file: PatchFile): string => {
+  // FNV-1a over the hunk text; collisions only cost a stale check, never correctness.
+  let hash = 0x811c9dc5;
+  for (const hunk of file.hunks) {
+    for (const line of [hunk.header, ...hunk.lines]) {
+      for (let index = 0; index < line.length; index++) {
+        hash ^= line.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+      }
+      hash ^= 10;
+      hash = Math.imul(hash, 0x01000193);
+    }
+  }
+  return (hash >>> 0).toString(36);
+};

package/src/components/PullRequestFiles/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './DiffStat.tsx';
+export * from './files.ts';
+export * from './FileTree.tsx';
+export * from './PullRequestFiles.tsx';

package/src/components/PullRequestOverview/ArtifactPill.tsx

@@ -0,0 +1,82 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { type ReactNode } from 'react';
+
+import * as Button from '@dxos/react-ui/Button';
+import * as Popover from '@dxos/react-ui/Popover';
+
+import { type ArtifactKind, type ArtifactLink } from '../../pull-request-body.ts';
+
+/** The leading icon for each kind of artifact. */
+export const artifactIcon: Record<ArtifactKind, string> = {
+  video: 'ph--film-strip--regular',
+  image: 'ph--image--regular',
+  file: 'ph--file--regular',
+};
+
+/** The image or video itself, or nothing for a file the browser cannot show inline. */
+export const ArtifactMedia = ({ artifact, classNames }: { artifact: ArtifactLink; classNames?: string }) =>
+  artifact.kind === 'video' ? (
+    <video
+      src={artifact.url}
+      controls
+      muted
+      playsInline
+      preload='metadata'
+      className={['block w-full bg-black rounded-sm', classNames].filter(Boolean).join(' ')}
+      data-testid='pull-request.artifact.video'
+    />
+  ) : artifact.kind === 'image' ? (
+    <img
+      src={artifact.url}
+      alt={artifact.label ?? artifact.name}
+      loading='lazy'
+      className={['block w-full object-contain rounded-sm', classNames].filter(Boolean).join(' ')}
+      data-testid='pull-request.artifact.image'
+    />
+  ) : null;
+
+export type ArtifactPillProps = {
+  artifact: ArtifactLink;
+  /** The link's text; the file name when it was written bare. */
+  children?: ReactNode;
+};
+
+/**
+ * An artifact link as a pill that previews its image or video in place, so a reader sees the demo
+ * without leaving the pull request. The outline matches the anchor chip a GitHub link becomes, so
+ * the body's links read as one kind of thing.
+ */
+export const ArtifactPill = ({ artifact, children }: ArtifactPillProps) => {
+  const label = typeof children === 'string' && children !== artifact.url ? children : artifact.name;
+  if (artifact.kind === 'file') {
+    return (
+      <a href={artifact.url} target='_blank' rel='noopener noreferrer' className='dx-tag-anchor'>
+        {label}
+      </a>
+    );
+  }
+
+  return (
+    <Popover.Root autoFocus={false}>
+      <Popover.Trigger asChild>
+        <Button.Root
+          hue='neutral'
+          size='sm'
+          classNames='bg-input-surface text-fg font-normal ring-inset ring ring-neutral-border hover:bg-hover-surface hover:ring-info-border align-baseline'
+          icon={artifactIcon[artifact.kind]}
+          iconClassNames={artifact.kind === 'video' ? 'text-violet-text' : 'text-sky-text'}
+          label={label}
+          data-testid='pull-request.artifact.pill'
+        />
+      </Popover.Trigger>
+      <Popover.Content classNames='w-[min(40rem,90vw)]'>
+        <Popover.Body classNames='p-1'>
+          <ArtifactMedia artifact={artifact} />
+        </Popover.Body>
+      </Popover.Content>
+    </Popover.Root>
+  );
+};

package/src/components/PullRequestOverview/CheckRunList.test.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { formatDuration } from './CheckRunList.tsx';
+
+describe('formatDuration', () => {
+  const startedAt = '2026-10-08T10:00:00Z';
+
+  test('measures a finished run from start to completion', ({ expect }) => {
+    expect(formatDuration(startedAt, '2026-10-08T10:04:12Z')).toBe('4m 12s');
+    expect(formatDuration(startedAt, '2026-10-08T10:00:42Z')).toBe('42s');
+  });
+
+  test('measures a running run up to now', ({ expect }) => {
+    expect(formatDuration(startedAt, undefined, Date.parse('2026-10-08T10:12:05Z'))).toBe('12m 5s');
+  });
+
+  test('prefers completion over now', ({ expect }) => {
+    expect(formatDuration(startedAt, '2026-10-08T10:01:00Z', Date.parse('2026-10-08T11:00:00Z'))).toBe('1m 0s');
+  });
+
+  test('is undefined without a start, or without an end of either kind', ({ expect }) => {
+    expect(formatDuration(undefined, '2026-10-08T10:01:00Z')).toBeUndefined();
+    expect(formatDuration(startedAt)).toBeUndefined();
+  });
+});

package/src/components/PullRequestOverview/CheckRunList.tsx

@@ -0,0 +1,141 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useEffect, useMemo, useState } from 'react';
+
+import { Listbox } from '@dxos/react-ui-list';
+import * as Hooks from '@dxos/react-ui/Hooks';
+import * as Status from '@dxos/react-ui/Status';
+
+import { meta } from '#meta';
+import { type GitHubOperation } from '#types';
+
+const outcomeIcon: Record<GitHubOperation.CheckOutcome, { icon: string; classNames: string }> = {
+  failure: { icon: 'ph--x-circle--fill', classNames: 'text-error-text' },
+  pending: { icon: 'ph--circle-notch--regular', classNames: 'text-warning-text animate-spin' },
+  success: { icon: 'ph--check-circle--fill', classNames: 'text-success-text' },
+  neutral: { icon: 'ph--minus-circle--regular', classNames: 'text-fg-muted' },
+  skipped: { icon: 'ph--prohibit--regular', classNames: 'text-fg-muted' },
+};
+
+// What needs attention first: a failure is the reason to open the list, a running check the next.
+const outcomeOrder: GitHubOperation.CheckOutcome[] = ['failure', 'pending', 'success', 'neutral', 'skipped'];
+
+/**
+ * `4m 12s` from start to finish, or to `now` for a run still in progress;
+ * undefined for a run that has not started, or has not finished when no `now` is given.
+ */
+export const formatDuration = (startedAt?: string, completedAt?: string, now?: number): string | undefined => {
+  const end = completedAt ? Date.parse(completedAt) : now;
+  if (!startedAt || end === undefined) {
+    return undefined;
+  }
+  const seconds = Math.max(0, Math.round((end - Date.parse(startedAt)) / 1000));
+  if (Number.isNaN(seconds)) {
+    return undefined;
+  }
+  const minutes = Math.floor(seconds / 60);
+  return minutes > 0 ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
+};
+
+/** The current time, re-rendering once a second while `active` so elapsed times stay current. */
+const useNow = (active: boolean): number => {
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!active) {
+      return;
+    }
+    setNow(Date.now());
+    const interval = setInterval(() => setNow(Date.now()), 1_000);
+    return () => clearInterval(interval);
+  }, [active]);
+  return now;
+};
+
+/** Sorts runs by what needs attention, then by name so shards read in order. */
+export const sortCheckRuns = (runs: readonly GitHubOperation.CheckRun[]): GitHubOperation.CheckRun[] =>
+  [...runs].sort(
+    (a, b) =>
+      outcomeOrder.indexOf(a.outcome) - outcomeOrder.indexOf(b.outcome) ||
+      a.name.localeCompare(b.name, undefined, { numeric: true }),
+  );
+
+export type CheckRunListProps = {
+  /** Undefined while the status is loading. */
+  runs?: readonly GitHubOperation.CheckRun[];
+};
+
+/** Every check on the head commit: its outcome, how long it took, and its logs a click away. */
+export const CheckRunList = ({ runs }: CheckRunListProps) => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  const sorted = useMemo(() => (runs ? sortCheckRuns(runs) : undefined), [runs]);
+  const summary = useCheckSummary(runs);
+  const now = useNow(runs?.some((run) => run.outcome === 'pending' && run.startedAt) ?? false);
+
+  if (!sorted || sorted.length === 0) {
+    return <Status.Empty>{t(sorted ? 'no-checks.message' : 'checks-loading.message')}</Status.Empty>;
+  }
+
+  return (
+    <Listbox.Root items={sorted.map((run) => ({ value: `${run.name}-${run.url ?? ''}`, label: run.name }))}>
+      <Listbox.Content aria-label={summary} data-testid='pull-request.checks'>
+        {sorted.map((run) => {
+          const { icon, classNames } = outcomeIcon[run.outcome];
+          const duration = formatDuration(run.startedAt, run.completedAt, run.outcome === 'pending' ? now : undefined);
+          // GitHub's own word when it says more than the outcome: `timed out` rather than `failed`.
+          const detail =
+            run.conclusion && run.conclusion !== run.outcome && run.conclusion !== 'failure'
+              ? run.conclusion.replace(/_/g, ' ')
+              : undefined;
+          const outcome =
+            run.outcome === 'skipped'
+              ? t('check-outcome.skipped.label')
+              : run.outcome === 'pending'
+                ? [t('check-outcome.pending.label'), duration].filter(Boolean).join(' · ')
+                : (duration ?? t(`check-outcome.${run.outcome}.label`));
+          const url = run.url;
+          return (
+            <Listbox.Item
+              key={`${run.name}-${url ?? ''}`}
+              id={`${run.name}-${url ?? ''}`}
+              data-outcome={run.outcome}
+              data-testid='pull-request.check'
+              onClick={url ? () => window.open(url, '_blank', 'noopener,noreferrer') : undefined}
+            >
+              <Listbox.ItemIcon icon={icon} classNames={classNames} />
+              <Listbox.ItemText>{run.name}</Listbox.ItemText>
+              <Listbox.ItemDescription>{[detail, outcome].filter(Boolean).join(' · ')}</Listbox.ItemDescription>
+            </Listbox.Item>
+          );
+        })}
+      </Listbox.Content>
+    </Listbox.Root>
+  );
+};
+
+/** The label the checks section carries: the counts once there are runs to count. */
+export const useCheckSummary = (runs?: readonly GitHubOperation.CheckRun[]): string => {
+  const { t } = Hooks.useTranslation(meta.profile.key);
+  return useMemo(() => {
+    if (!runs || runs.length === 0) {
+      return t('checks.label');
+    }
+    const counts: Record<GitHubOperation.CheckOutcome, number> = {
+      success: 0,
+      failure: 0,
+      pending: 0,
+      skipped: 0,
+      neutral: 0,
+    };
+    for (const run of runs) {
+      counts[run.outcome]++;
+    }
+    return t('checks-summary.label', {
+      passed: counts.success + counts.neutral,
+      failed: counts.failure,
+      pending: counts.pending,
+      skipped: counts.skipped,
+    });
+  }, [runs, t]);
+};

package/src/components/PullRequestOverview/PullRequestDetails.tsx

@@ -0,0 +1,15 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+/** What the overview's details section shows, as a read-only form: one row per fact about the pull request. */
+export const PullRequestDetailsSchema = Schema.Struct({
+  reference: Schema.String.annotate({ title: 'Pull request' }),
+  state: Schema.optional(Schema.String.annotate({ title: 'State' })),
+  checks: Schema.optional(Schema.String.annotate({ title: 'Checks' })),
+  branches: Schema.optional(Schema.String.annotate({ title: 'Branches' })),
+});
+
+export type PullRequestDetailsValues = Schema.Schema.Type<typeof PullRequestDetailsSchema>;

package/src/components/PullRequestOverview/PullRequestOverview.tsx

@@ -0,0 +1,110 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import * as Hooks from '@dxos/app-framework/Hooks';
+import { DxAnchor } from '@dxos/lit-ui/react';
+import * as PreviewCapabilities from '@dxos/plugin-preview/PreviewCapabilities';
+import { Form } from '@dxos/react-ui-form';
+import { MarkdownLink, MarkdownView, type MarkdownViewProps } from '@dxos/react-ui-markdown';
+import * as UiHooks from '@dxos/react-ui/Hooks';
+import * as Icon from '@dxos/react-ui/Icon';
+import * as Status from '@dxos/react-ui/Status';
+
+import { meta } from '#meta';
+import { type GitHubOperation } from '#types';
+
+import { parseArtifactLink, parsePullRequestBody } from '../../pull-request-body.ts';
+import { ArtifactPill } from './ArtifactPill.tsx';
+import { CheckRunList, useCheckSummary } from './CheckRunList.tsx';
+import { PullRequestDetailsSchema, type PullRequestDetailsValues } from './PullRequestDetails.tsx';
+import { RelatedCards, useRelatedItems } from './RelatedCards.tsx';
+
+export type PullRequestOverviewProps = {
+  /** The pull request's description as written on GitHub, footers included. */
+  body?: string;
+  details: PullRequestDetailsValues;
+  /** Undefined while the status is loading. */
+  runs?: readonly GitHubOperation.CheckRun[];
+};
+
+/**
+ * A pull request as its author presented it: the description, the facts about it, what it links to
+ * beyond the diff, and every check on its head commit.
+ */
+export const PullRequestOverview = ({ body, details, runs }: PullRequestOverviewProps) => {
+  const { t } = UiHooks.useTranslation(meta.profile.key);
+  const parsed = useMemo(() => parsePullRequestBody(body), [body]);
+  const components = useBodyComponents();
+  const related = useRelatedItems(parsed);
+  const checkSummary = useCheckSummary(runs);
+
+  // One form hosts the whole tab, so the description and every section share its viewport's column
+  // rather than each nesting a gutter of its own.
+  return (
+    <Form.Root schema={PullRequestDetailsSchema} values={details} layout='static' readonly>
+      <Form.Viewport scroll width='document'>
+        <Form.Content>
+          {parsed.markdown ? (
+            <MarkdownView content={parsed.markdown} components={components} data-testid='pull-request.body' />
+          ) : (
+            <Status.Empty>{t('no-description.message')}</Status.Empty>
+          )}
+          <Form.FieldSet label={t('details.label')} data-testid='pull-request.details'>
+            <Form.Fields />
+          </Form.FieldSet>
+          {related.length > 0 && (
+            <Form.FieldSet label={t('related.label')}>
+              <RelatedCards items={related} />
+            </Form.FieldSet>
+          )}
+          <Form.FieldSet label={checkSummary}>
+            <CheckRunList runs={runs} />
+          </Form.FieldSet>
+        </Form.Content>
+      </Form.Viewport>
+    </Form.Root>
+  );
+};
+
+/**
+ * Links in the body as pills: an artifact previews its media in place, and a link a preview
+ * resolver answers (another pull request, an issue) becomes the anchor chip the editor makes of it.
+ */
+const useBodyComponents = (): MarkdownViewProps['components'] => {
+  const resolvers = Hooks.useCapabilities(PreviewCapabilities.LinkResolver);
+  return useMemo(
+    () => ({
+      a: ({ children, href, node: _node, ...props }) => {
+        const artifact = href ? parseArtifactLink(href) : undefined;
+        if (artifact) {
+          return <ArtifactPill artifact={artifact}>{children}</ArtifactPill>;
+        }
+        const all = resolvers.flat();
+        if (!href || !PreviewCapabilities.isPreviewLink(all, href)) {
+          return (
+            <MarkdownLink href={href} {...props}>
+              {children}
+            </MarkdownLink>
+          );
+        }
+        const icon = PreviewCapabilities.linkIcon(all, href);
+        return (
+          <DxAnchor eid={href} className='dx-tag-anchor'>
+            {icon && (
+              <Icon.Icon
+                icon={icon.icon}
+                size='md'
+                classNames={['inline-block align-[-0.125em] me-1', icon.classNames]}
+              />
+            )}
+            {children === href ? (PreviewCapabilities.linkLabel(all, href) ?? children) : children}
+          </DxAnchor>
+        );
+      },
+    }),
+    [resolvers],
+  );
+};