@dxos/plugin-github 0.7.4-staging.f7e8224 → 0.13.0

package/src/types/PullRequestsView.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { ViewState } from '@dxos/react-ui-attention/types';
+
+/**
+ * The fields the pull request list can be ordered by. `relevance` ranks what needs the reader first
+ * (see `relevance`); `updated` and `created` are GitHub's times.
+ */
+export const SortField = Schema.Literals(['relevance', 'updated', 'created', 'number', 'title']);
+export type SortField = Schema.Schema.Type<typeof SortField>;
+
+export const SortDirection = Schema.Literals(['asc', 'desc']);
+export type SortDirection = Schema.Schema.Type<typeof SortDirection>;
+
+export const Sort = Schema.Struct({ field: SortField, direction: SortDirection });
+export type Sort = Schema.Schema.Type<typeof Sort>;
+
+/** The fields the list can be grouped by; `none` is one ungrouped list. */
+export const GroupField = Schema.Literals(['none', 'repo', 'state', 'checks', 'author']);
+export type GroupField = Schema.Schema.Type<typeof GroupField>;
+
+export const DEFAULT_SORT: Sort = { field: 'relevance', direction: 'desc' };
+
+export const View = Schema.Struct({
+  query: Schema.String,
+  sort: Schema.optional(Sort),
+  group: Schema.optional(GroupField),
+});
+export type View = Schema.Schema.Type<typeof View>;
+
+/**
+ * How a reader has the space's pull requests arranged, keyed by the space and held per device
+ * (`local`), as a task set's list is: the filter, order and grouping are how this reader looks at the
+ * list here, not a property of the space every member would see.
+ */
+export const aspect: ViewState.Aspect<View> = ViewState.define<View>({
+  key: 'github-pull-requests-view',
+  backend: 'local',
+  schema: View,
+  defaultValue: (): View => ({ query: '' }),
+});

package/src/types/Walkthrough.test.ts

@@ -0,0 +1,75 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { Obj, Ref } from '@dxos/echo';
+import { PullRequest } from '@dxos/types';
+
+import * as Walkthrough from './Walkthrough.ts';
+
+describe('Walkthrough', () => {
+  test('holds the body, the commit and a ref to the pull request', () => {
+    const pullRequest = makePullRequest();
+    const walkthrough = Walkthrough.make({
+      pullRequest: Ref.make(pullRequest),
+      body: '# A change\n\nProse.\n',
+      commit: 'deadbeef',
+    });
+
+    expect(Walkthrough.instanceOf(walkthrough)).to.eq(true);
+    expect(walkthrough.body).to.eq('# A change\n\nProse.\n');
+    expect(walkthrough.commit).to.eq('deadbeef');
+    expect(walkthrough.pullRequest.target).to.eq(pullRequest);
+  });
+
+  test('is labelled by its title, falling back to the commit', () => {
+    const pullRequest = makePullRequest();
+    const titled = Walkthrough.make({
+      pullRequest: Ref.make(pullRequest),
+      title: Walkthrough.makeTitle(pullRequest),
+      body: 'text',
+      commit: 'abc',
+    });
+    const untitled = Walkthrough.make({ pullRequest: Ref.make(pullRequest), body: 'text', commit: 'abc' });
+
+    expect(Obj.getLabel(titled)).to.eq(`${PullRequest.reference(pullRequest)}: ${pullRequest.title}`);
+    expect(Obj.getLabel(untitled)).to.eq('abc');
+  });
+
+  test('the body is a plain string, not a text object', () => {
+    const walkthrough = Walkthrough.make({
+      pullRequest: Ref.make(makePullRequest()),
+      body: 'text',
+      commit: 'abc',
+    });
+
+    // A text object would replicate as a CRDT; this is replaced wholesale on every regeneration.
+    expect(typeof walkthrough.body).to.eq('string');
+  });
+
+  test('is stale against any commit but the one it was generated from', () => {
+    const walkthrough = Walkthrough.make({
+      pullRequest: Ref.make(makePullRequest()),
+      body: '',
+      commit: 'abc123',
+    });
+
+    expect(Walkthrough.isStale(walkthrough, 'abc123')).to.eq(false);
+    expect(Walkthrough.isStale(walkthrough, 'def456')).to.eq(true);
+  });
+
+  test('is an ECHO object of the expected type', () => {
+    const walkthrough = Walkthrough.make({
+      pullRequest: Ref.make(makePullRequest()),
+      body: '',
+      commit: 'abc',
+    });
+
+    expect(Obj.getTypename(walkthrough)).to.eq('org.dxos.type.walkthrough');
+  });
+});
+
+const makePullRequest = () =>
+  PullRequest.make({ owner: 'dxos', repo: 'dxos', number: 13082, title: 'A change', state: 'open' });

package/src/types/Walkthrough.ts

@@ -0,0 +1,66 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+import * as Schema from 'effect/Schema';
+
+import { Annotation, DXN, Format, Obj, Ref, Type } from '@dxos/echo';
+import { PullRequest } from '@dxos/types';
+
+/**
+ * A narrated reading of a pull request: one markdown document whose prose, headings and ```diff
+ * fences describe the change in the order a reviewer should meet it.
+ *
+ * Generated against ONE commit and stale the moment the branch moves, which is why `commit` is part
+ * of the record rather than something to infer — see {@link isStale}.
+ */
+export class Walkthrough extends Type.makeObject<Walkthrough>(DXN.make('org.dxos.type.walkthrough', '0.1.0'))(
+  Schema.Struct({
+    /** The pull request this narrates. */
+    pullRequest: Ref.Ref(PullRequest.PullRequest),
+
+    /** `owner/repo#123: title`, copied at generation so the label needs no ref load. */
+    title: Schema.String.pipe(Schema.annotate({ title: 'Title' }), Schema.optional),
+
+    /**
+     * The whole document, as a plain string rather than a text object.
+     *
+     * A walkthrough is replaced wholesale on every regeneration and is never co-edited character by
+     * character, so the CRDT a text object would impose is pure cost: it would keep per-character
+     * history for a document nobody edits.
+     */
+    body: Schema.String.pipe(Schema.annotate({ title: 'Body' })),
+
+    /** Head SHA the walkthrough was generated from; anything else means it describes another change. */
+    commit: Schema.String.pipe(Schema.annotate({ title: 'Commit' })),
+
+    generatedAt: Format.DateTime.pipe(Schema.annotate({ title: 'Generated' }), Schema.optional),
+
+    /** Model that produced the prose, so a regression can be attributed after the default moves. */
+    model: Schema.String.pipe(Schema.annotate({ title: 'Model' }), Schema.optional),
+
+    /** Hunks the prose accounts for, over the patch's total — how much of the change it narrates. */
+    covered: Schema.Number.pipe(Schema.annotate({ title: 'Hunks covered' }), Schema.optional),
+    total: Schema.Number.pipe(Schema.annotate({ title: 'Hunks total' }), Schema.optional),
+  }).pipe(
+    Schema.annotate({ title: 'Walkthrough', description: 'A narrated reading of a pull request.' }),
+    Annotation.LabelAnnotation.set(['title', 'commit']),
+    Annotation.IconAnnotation.set({ icon: 'ph--path--regular', hue: 'indigo' }),
+    Annotation.UserType.set(),
+  ),
+) {}
+
+/** Factory wrapper around `Obj.make` for {@link Walkthrough}. */
+export const make = (props: Obj.MakeProps<typeof Walkthrough>): Walkthrough => Obj.make(Walkthrough, props);
+
+/** Returns true when value is a Walkthrough object. */
+export const instanceOf = (value: unknown): value is Walkthrough => Obj.instanceOf(Walkthrough, value);
+
+/** The label a walkthrough of this pull request carries. */
+export const makeTitle = (pullRequest: PullRequest.PullRequest, title = pullRequest.title): string =>
+  `${PullRequest.reference(pullRequest)}: ${title}`;
+
+/** Whether the walkthrough describes a commit other than the one given. */
+export const isStale = (walkthrough: Walkthrough, head: string): boolean => walkthrough.commit !== head;

package/src/types/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * as GitHubCapabilities from './GitHubCapabilities.ts';
+export * as GitHubEvents from './GitHubEvents.ts';
+export * as GitHubOperation from './GitHubOperation.ts';
+export * as Walkthrough from './Walkthrough.ts';

package/src/vite-env.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}
+
+declare module '*.patch?raw' {
+  const content: string;
+  export default content;
+}

package/src/walkthrough/fill.test.ts

@@ -0,0 +1,337 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { fillWalkthrough } from './fill.ts';
+import { parsePatch } from './patch.ts';
+
+const PATCH = [
+  'diff --git a/src/a.ts b/src/a.ts',
+  'index 111..222 100644',
+  '--- a/src/a.ts',
+  '+++ b/src/a.ts',
+  '@@ -10,3 +10,4 @@ const first = () => {',
+  ' keep();',
+  '-was();',
+  '+is();',
+  '+added();',
+  '@@ -90,2 +91,2 @@ const second = () => {',
+  ' context();',
+  '-old();',
+  '+new();',
+  'diff --git a/src/b.ts b/src/b.ts',
+  'index 333..444 100644',
+  '--- a/src/b.ts',
+  '+++ b/src/b.ts',
+  '@@ -1,1 +1,2 @@',
+  ' header();',
+  '+extra();',
+  '',
+].join('\n');
+
+describe('parsePatch', () => {
+  test('splits files and hunks with post-change spans', () => {
+    const files = parsePatch(PATCH);
+
+    expect(files.map((file) => file.path)).to.deep.eq(['src/a.ts', 'src/b.ts']);
+    expect(files[0].hunks).to.have.length(2);
+    expect(files[0].hunks[0].afterStart).to.eq(10);
+    expect(files[0].hunks[0].afterEnd).to.eq(13);
+    expect(files[0].hunks[1].afterStart).to.eq(91);
+    expect(files[0].added).to.eq(3);
+    expect(files[0].removed).to.eq(2);
+    expect(files[1].hunks[0].lines).to.deep.eq([' header();', '+extra();']);
+  });
+
+  test('keeps hunk bodies verbatim', () => {
+    const [first] = parsePatch(PATCH);
+    expect(first.hunks[0].header).to.eq('@@ -10,3 +10,4 @@ const first = () => {');
+    expect(first.hunks[0].lines).to.deep.eq([' keep();', '-was();', '+is();', '+added();']);
+  });
+
+  test('reads a hunk header with no count', () => {
+    const [file] = parsePatch(
+      ['diff --git a/src/c.ts b/src/c.ts', '--- a/src/c.ts', '+++ b/src/c.ts', '@@ -5 +5 @@', '-a;', '+b;'].join('\n'),
+    );
+    expect(file.hunks[0].afterStart).to.eq(5);
+    expect(file.hunks[0].afterEnd).to.eq(5);
+  });
+});
+
+describe('fillWalkthrough', () => {
+  test('fills an empty fence from the patch and states the real range', () => {
+    const body = ['# Change', '', 'Some prose.', '', '```diff file=src/a.ts lines=10-13', '```', ''].join('\n');
+    const { body: filled, covered } = fillWalkthrough(body, PATCH);
+
+    expect(filled).to.contain('```diff file=src/a.ts lines=10-13');
+    expect(filled).to.contain('@@ -10,3 +10,4 @@ const first = () => {');
+    expect(filled).to.contain('+added();');
+    // The second hunk of the same file is outside the requested range, so it is not in the chunk
+    // (it reappears below, under the section for what the walkthrough missed).
+    const [narrated] = filled.split('## Also changed');
+    expect(narrated).to.not.contain('+new();');
+    expect(covered).to.eq(1);
+  });
+
+  test('takes every hunk of a file when the fence states no range', () => {
+    const body = ['```diff file=src/a.ts', '```', ''].join('\n');
+    const { body: filled, covered } = fillWalkthrough(body, PATCH);
+
+    expect(filled).to.contain('@@ -10,3 +10,4 @@');
+    expect(filled).to.contain('@@ -90,2 +91,2 @@');
+    expect(filled).to.contain('lines=10-92');
+    expect(covered).to.eq(2);
+  });
+
+  test('appends the hunks the prose never mentioned', () => {
+    const body = ['# Change', '', '```diff file=src/a.ts lines=10-13', '```', ''].join('\n');
+    const { body: filled, missed } = fillWalkthrough(body, PATCH);
+
+    expect(missed.map((file) => file.path)).to.deep.eq(['src/a.ts', 'src/b.ts']);
+    expect(filled).to.contain('## Also changed');
+    expect(filled).to.contain('2 hunks across 2 files');
+    expect(filled).to.contain('+new();');
+    expect(filled).to.contain('+extra();');
+  });
+
+  test('appends nothing when the walkthrough covers the patch', () => {
+    const body = ['```diff file=src/a.ts', '```', '', '```diff file=src/b.ts', '```', ''].join('\n');
+    const { body: filled, missed, covered, total } = fillWalkthrough(body, PATCH);
+
+    expect(missed).to.deep.eq([]);
+    expect(covered).to.eq(total);
+    expect(filled).to.not.contain('## Also changed');
+  });
+
+  test('leaves a fence naming an unknown file alone and reports it', () => {
+    const body = ['```diff file=src/gone.ts', '```', ''].join('\n');
+    const { body: filled, unresolved } = fillWalkthrough(body, PATCH);
+
+    expect(unresolved).to.deep.eq(['src/gone.ts']);
+    expect(filled).to.contain('```diff file=src/gone.ts');
+  });
+
+  test('leaves a fence the model filled itself, and still shows the real hunks below', () => {
+    const body = ['```diff file=src/a.ts lines=10-13', '@@ -1,1 +1,1 @@', '+hand written;', '```', ''].join('\n');
+    const { body: filled, covered } = fillWalkthrough(body, PATCH);
+
+    expect(filled).to.contain('+hand written;');
+    // Content the model wrote covers nothing: the genuine hunk still has to reach the reader, or a
+    // model that ignores the instruction silently replaces the change with its own account of it.
+    expect(covered).to.eq(0);
+    const [, appended] = filled.split('## Also changed');
+    expect(appended).to.contain('+added();');
+  });
+
+  test('accepts a bare path on the fence', () => {
+    const { body: filled } = fillWalkthrough(['```diff src/b.ts', '```', ''].join('\n'), PATCH);
+    expect(filled).to.contain('+extra();');
+  });
+
+  test('leaves prose around a fence untouched', () => {
+    const body = ['Before.', '', '```diff file=src/b.ts', '```', '', 'After.', ''].join('\n');
+    const { body: filled } = fillWalkthrough(body, PATCH);
+
+    expect(filled.startsWith('Before.\n')).to.eq(true);
+    expect(filled).to.contain('\nAfter.');
+  });
+
+  test('reads a patch with carriage returns', () => {
+    const { body: filled, total } = fillWalkthrough(
+      ['```diff file=src/b.ts', '```', ''].join('\n'),
+      PATCH.split('\n').join('\r\n'),
+    );
+
+    // Left in place the carriage returns defeat every anchored match, and the whole patch parses to
+    // nothing: an empty walkthrough that claims to have covered everything.
+    expect(total).to.eq(3);
+    expect(filled).to.contain('+extra();');
+  });
+
+  test('selects a pure-deletion hunk by its own reported range', () => {
+    const patch = [
+      'diff --git a/src/d.ts b/src/d.ts',
+      '--- a/src/d.ts',
+      '+++ b/src/d.ts',
+      '@@ -1,1 +1,1 @@',
+      ' first();',
+      '@@ -10,2 +10,0 @@',
+      '-gone();',
+      '-also();',
+    ].join('\n');
+    const { body: filled, covered } = fillWalkthrough(['```diff file=src/d.ts lines=10', '```', ''].join('\n'), patch);
+
+    // The post-image span of a removal is empty, so a naive overlap test can never match it and the
+    // fence silently widens to the whole file.
+    expect(covered).to.eq(1);
+    const [narrated] = filled.split('## Also changed');
+    expect(narrated).to.contain('-gone();');
+    expect(narrated).to.contain('lines=10-11');
+    // The other hunk is not in the fence; it reappears below, as anything unclaimed does.
+    expect(narrated).to.not.contain(' first();');
+  });
+
+  test('keeps a fence indented inside a list item', () => {
+    const body = ['1. A step:', '', '   ```diff file=src/b.ts', '   ```', ''].join('\n');
+    const { body: filled } = fillWalkthrough(body, PATCH);
+
+    // An unindented closing fence ends the list item's block, not the fence. Scoped to the narrated
+    // part: the appended section is top-level prose and its fences are correctly unindented.
+    const [narrated] = filled.split('## Also changed');
+    expect(narrated).to.contain('   ```diff file=src/b.ts');
+    expect(narrated).to.contain('   +extra();');
+    expect(
+      narrated
+        .split('\n')
+        .filter((line) => line.trim() === '```')
+        .every((line) => line.startsWith('   ')),
+    ).to.eq(true);
+  });
+
+  test('reports a fence that names no file', () => {
+    const { body: filled, unresolved } = fillWalkthrough(['```diff', '```', ''].join('\n'), PATCH);
+
+    expect(unresolved).to.have.length(1);
+    expect(filled).to.contain('```diff');
+  });
+
+  test('names a file the patch changed without changing a line', () => {
+    const patch = [
+      'diff --git a/old.ts b/new.ts',
+      'similarity index 100%',
+      'rename from old.ts',
+      'rename to new.ts',
+    ].join('\n');
+    const { body: filled, textless, total } = fillWalkthrough('# Change\n', patch);
+
+    expect(total).to.eq(0);
+    expect(textless).to.deep.eq(['new.ts']);
+    expect(filled).to.contain('renamed or mode-only');
+    expect(filled).to.contain('new.ts');
+  });
+
+  test('names generated and binary files without rendering their hunks', () => {
+    const patch = [
+      PATCH,
+      'diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml',
+      '--- a/pnpm-lock.yaml',
+      '+++ b/pnpm-lock.yaml',
+      '@@ -1,1 +1,2 @@',
+      ' lockfileVersion: 9',
+      '+  resolution: {integrity: sha512-whatever}',
+      'diff --git a/assets/logo.png b/assets/logo.png',
+      'Binary files a/assets/logo.png and b/assets/logo.png differ',
+      '',
+    ].join('\n');
+    const { body: filled, generated, missed } = fillWalkthrough('# Change\n', patch);
+
+    expect(generated).to.deep.eq(['pnpm-lock.yaml', 'assets/logo.png']);
+    expect(filled).to.contain('Generated or binary, not shown: pnpm-lock.yaml, assets/logo.png.');
+    expect(filled).to.not.contain('sha512-whatever');
+    expect(missed.map((file) => file.path)).to.not.include('pnpm-lock.yaml');
+  });
+
+  test('drops a fence that points at a generated file rather than rendering it', () => {
+    const patch = [
+      PATCH,
+      'diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml',
+      '--- a/pnpm-lock.yaml',
+      '+++ b/pnpm-lock.yaml',
+      '@@ -1,1 +1,2 @@',
+      ' lockfileVersion: 9',
+      '+  resolution: {integrity: sha512-whatever}',
+      '',
+    ].join('\n');
+    const body = '# Change\n\nThe lockfile moved too.\n\n```diff file=pnpm-lock.yaml\n```\n';
+    const { body: filled, total } = fillWalkthrough(body, patch);
+
+    expect(filled).to.not.contain('sha512-whatever');
+    expect(filled).to.contain('The lockfile moved too.');
+    expect(filled).to.contain('Generated or binary, not shown: pnpm-lock.yaml.');
+    // The denominator drops with `missed`, or a walkthrough covering everything worth reading
+    // would report partial coverage.
+    expect(total).to.eq(3);
+  });
+
+  test('ends the range at a pure removal that a live hunk shares the fence with', () => {
+    const patch = [
+      'diff --git a/src/mixed.ts b/src/mixed.ts',
+      '--- a/src/mixed.ts',
+      '+++ b/src/mixed.ts',
+      '@@ -1,1 +1,2 @@',
+      ' keep();',
+      '+added();',
+      // A pure removal spans nothing after the change: `afterEnd` is 98 while it sits at 99.
+      '@@ -100,1 +99,0 @@',
+      '-gone();',
+    ].join('\n');
+    const { body: filled } = fillWalkthrough(['```diff file=src/mixed.ts', '```', ''].join('\n'), patch);
+
+    expect(filled).to.contain('lines=1-99');
+  });
+
+  test('does not call a textless file unresolved as well', () => {
+    const patch = [
+      'diff --git a/old.ts b/new.ts',
+      'similarity index 100%',
+      'rename from old.ts',
+      'rename to new.ts',
+    ].join('\n');
+    const { textless, unresolved } = fillWalkthrough(['```diff file=new.ts', '```', ''].join('\n'), patch);
+
+    // The patch does contain the file; `unresolved` is for one it does not.
+    expect(textless).to.deep.eq(['new.ts']);
+    expect(unresolved).to.deep.eq([]);
+  });
+
+  test('emits no dangling attribute for a file it cannot fill', () => {
+    const patch = ['diff --git a/old.ts b/new.ts', 'similarity index 100%'].join('\n');
+    const { body: filled } = fillWalkthrough(['```diff file=new.ts', '```', ''].join('\n'), patch);
+
+    // `lines=` with no value is not a fence the editor reads; it renders as a bare code block.
+    expect(filled).to.not.contain('lines=\n');
+    expect(filled).to.not.contain('lines= ');
+  });
+
+  test('merges hunks of a path the patch names twice', () => {
+    const patch = [
+      'diff --git a/src/x.ts b/src/x.ts',
+      '@@ -1,1 +1,2 @@',
+      ' a;',
+      '+one();',
+      'diff --git a/src/x.ts b/src/x.ts',
+      '@@ -50,1 +51,2 @@',
+      ' b;',
+      '+two();',
+    ].join('\n');
+    const { body: filled, total } = fillWalkthrough(['```diff file=src/x.ts', '```', ''].join('\n'), patch);
+
+    // Keyed by path, the second occurrence would otherwise hide the first from every fence.
+    expect(total).to.eq(2);
+    expect(filled).to.contain('+one();');
+    expect(filled).to.contain('+two();');
+  });
+
+  test('quotes a deleted file by the lines it removed', () => {
+    const patch = [
+      'diff --git a/src/gone.ts b/src/gone.ts',
+      'deleted file mode 100644',
+      '--- a/src/gone.ts',
+      '+++ /dev/null',
+      '@@ -1,2 +0,0 @@',
+      '-one();',
+      '-two();',
+    ].join('\n');
+    const { body: filled } = fillWalkthrough(['```diff file=src/gone.ts', '```', ''].join('\n'), patch);
+
+    // The post-image is empty, so an after-side range would read as `Lines 0`.
+    expect(filled).to.contain('lines=1-2');
+  });
+
+  test('falls back to the whole file when the stated range matches no hunk', () => {
+    const { body: filled } = fillWalkthrough(['```diff file=src/b.ts lines=400-500', '```', ''].join('\n'), PATCH);
+    expect(filled).to.contain('+extra();');
+  });
+});