@dxos/plugin-github 0.7.4 → 0.13.0

package/src/walkthrough/fill.ts

@@ -0,0 +1,246 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { isGeneratedFile } from './generated.ts';
+import { type PatchFile, type PatchHunk, hunkOverlaps, hunkRange, parsePatch, renderHunks } from './patch.ts';
+
+/** A diff fence the model emitted, located in the walkthrough body. */
+type Placeholder = {
+  /** Offsets of the whole fence, opening and closing lines included. */
+  from: number;
+  to: number;
+  /** The run of backticks or tildes that opened it, so the rewrite closes it the same way. */
+  fence: string;
+  /** Leading whitespace, which the replacement has to reproduce or it breaks its enclosing list. */
+  indent: string;
+  attributes: Record<string, string>;
+  /** Whether the model left the fence empty, which is the contract it is asked to follow. */
+  empty: boolean;
+};
+
+export type WalkthroughFill = {
+  body: string;
+  /** Hunks no fence claimed, in patch order — what the appended section covers. */
+  missed: { path: string; hunks: PatchHunk[] }[];
+  /** Files the patch changed without changing any line: renames and mode changes. */
+  textless: string[];
+  /** Machine-written or binary files, named in the appendix rather than rendered. */
+  generated: string[];
+  /** Fences naming a file the patch does not contain; left in place with a note. */
+  unresolved: string[];
+  /** Hunks the body accounts for, over the patch's total. */
+  covered: number;
+  total: number;
+};
+
+/**
+ * Opening fence plus its info line; the body is whatever follows up to the matching close. Built per
+ * call rather than shared: a `/g` regex carries `lastIndex` between uses.
+ *
+ * At most three spaces of indent, because four makes it an indented code block in CommonMark rather
+ * than a fence.
+ */
+const fencePattern = () => /^( {0,3})(`{3,}|~{3,})[ \t]*diff\b([^\n]*)$/gm;
+
+const parseAttributes = (info: string): Record<string, string> => {
+  const attributes: Record<string, string> = {};
+  for (const token of info.trim().match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []) {
+    const separator = token.indexOf('=');
+    if (separator > 0) {
+      attributes[token.slice(0, separator)] = token.slice(separator + 1).replace(/^["']|["']$/g, '');
+    } else if (!attributes.file) {
+      // A bare token is the path, matching what the editor's fence parser accepts.
+      attributes.file = token.replace(/^["']|["']$/g, '');
+    }
+  }
+
+  return attributes;
+};
+
+const findPlaceholders = (body: string): Placeholder[] => {
+  const placeholders: Placeholder[] = [];
+  const pattern = fencePattern();
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(body))) {
+    const [opening, indent, fence, info] = match;
+    const bodyStart = match.index + opening.length + 1;
+    // A fence closes on a line of at least as many of the same marker, per CommonMark.
+    const close = new RegExp(`^[ \\t]*${fence[0]}{${fence.length},}[ \\t]*$`, 'm');
+    close.lastIndex = 0;
+    const rest = body.slice(bodyStart);
+    const closeMatch = close.exec(rest);
+    const contents = closeMatch ? rest.slice(0, closeMatch.index) : rest;
+    const to = closeMatch ? bodyStart + closeMatch.index + closeMatch[0].length : body.length;
+    placeholders.push({
+      // Starts AT the indent, not after it: the replacement re-emits it on every line, so leaving it
+      // in the preceding slice would indent the opening fence twice.
+      from: match.index,
+      to,
+      fence,
+      indent,
+      attributes: parseAttributes(info),
+      empty: contents.trim().length === 0,
+    });
+    pattern.lastIndex = to;
+  }
+
+  return placeholders;
+};
+
+/** The hunks a fence asks for: those overlapping its `lines=`, or the whole file without one. */
+const selectHunks = (file: PatchFile, lines: string | undefined): PatchHunk[] => {
+  const range = lines?.match(/^(\d+)(?:\s*[-–]\s*(\d+))?$/);
+  if (!range) {
+    return file.hunks;
+  }
+  const start = Number(range[1]);
+  const end = range[2] === undefined ? start : Number(range[2]);
+  const selected = file.hunks.filter((hunk) => hunkOverlaps(hunk, start, end));
+  // A range that matches nothing is the model guessing; the file's hunks are better than an empty chunk.
+  return selected.length > 0 ? selected : file.hunks;
+};
+
+const buildFence = (fence: string, attributes: Record<string, string>, contents: string, indent = ''): string => {
+  const info = Object.entries(attributes)
+    // An attribute with no value would emit a dangling `lines=`, which is not a fence the editor reads.
+    .filter(([, value]) => value.length > 0)
+    .map(([key, value]) => `${key}=${/\s/.test(value) ? `"${value}"` : value}`)
+    .join(' ');
+  // Every line carries the opening fence's indent, or a fence inside a list item closes outside it.
+  const lines = [`${fence}diff${info ? ` ${info}` : ''}`, ...contents.split('\n'), fence];
+  return lines.map((line) => (line.length > 0 ? indent + line : line)).join('\n');
+};
+
+/**
+ * Fills the walkthrough's empty diff fences from the pull request's own patch, then reports what the
+ * prose never mentioned.
+ *
+ * The model is asked for placeholders — a path and a line range — rather than diff content, because
+ * a model that transcribes a diff gets lines subtly wrong and the result is a review artefact that
+ * lies about the change. Here the bytes come from git and only the selection is the model's.
+ */
+export const fillWalkthrough = (body: string, patch: string): WalkthroughFill => {
+  const files = parsePatch(patch);
+  const byPath = new Map(files.map((file) => [file.path, file]));
+  // Established before the fences are filled: a fence naming a lockfile would otherwise render it,
+  // which is the one thing the appendix exists to avoid.
+  const generated = files.filter((file) => isGeneratedFile(file)).map((file) => file.path);
+  const generatedPaths = new Set(generated);
+  const used = new Set<PatchHunk>();
+  const unresolved: string[] = [];
+
+  let filled = '';
+  let cursor = 0;
+  for (const placeholder of findPlaceholders(body)) {
+    const { file: path, ...rest } = placeholder.attributes;
+    const file = path ? byPath.get(path) : undefined;
+    const verbatim = body.slice(placeholder.from, placeholder.to);
+    filled += body.slice(cursor, placeholder.from);
+    cursor = placeholder.to;
+
+    // A fence the model filled itself is NOT counted as covering anything: its content is the
+    // model's own words, so the real hunks still have to reach the reader below.
+    if (!placeholder.empty) {
+      filled += verbatim;
+      continue;
+    }
+
+    // Kept verbatim rather than dropped: whatever the prose was pointing at is still worth seeing,
+    // and a fence naming nothing is the likeliest mistake a model makes.
+    if (!path) {
+      unresolved.push('(a fence with no file)');
+      filled += verbatim;
+      continue;
+    }
+    if (!file) {
+      unresolved.push(path);
+      filled += verbatim;
+      continue;
+    }
+
+    // The prose keeps its sentence, the fence goes: the appendix names the file, and rendering a
+    // lockfile's hunks costs more of the reader than the sentence pointing at it is worth.
+    if (generatedPaths.has(path)) {
+      continue;
+    }
+
+    // A rename, a mode change or a binary file has no hunks; there is nothing to splice, and an
+    // empty fence would render as a bare code block. NOT `unresolved`: the patch does contain this
+    // file, and `textless` already reports it — counting it as missing would say both at once.
+    const hunks = selectHunks(file, rest.lines);
+    if (hunks.length === 0) {
+      filled += verbatim;
+      continue;
+    }
+
+    for (const hunk of hunks) {
+      used.add(hunk);
+    }
+    filled += buildFence(
+      placeholder.fence,
+      { file: path, ...rest, lines: hunkRange(hunks) ?? rest.lines ?? '' },
+      renderHunks(hunks),
+      placeholder.indent,
+    );
+  }
+  filled += body.slice(cursor);
+
+  const missed = files
+    .map((file) => ({ path: file.path, hunks: file.hunks.filter((hunk) => !used.has(hunk)) }))
+    // A generated file is named in the appendix, never rendered: a lockfile's hunks are longer than
+    // the walkthrough and nobody reads them.
+    .filter((file) => file.hunks.length > 0 && !generatedPaths.has(file.path));
+  // A rename, a mode change or a binary file has no hunks to show, but the reader still has to learn
+  // it changed — counting it nowhere would report full coverage of a pull request nobody saw.
+  const textless = files
+    .filter((file) => file.hunks.length === 0 && !generatedPaths.has(file.path))
+    .map((file) => file.path);
+  // Generated hunks leave the denominator as well as `missed`: counting them would report a
+  // walkthrough as covering half a change when it covered all of the part worth reading.
+  const total = files
+    .filter((file) => !generatedPaths.has(file.path))
+    .reduce((count, file) => count + file.hunks.length, 0);
+  const appendix = renderMissed(missed, textless, generated);
+
+  return {
+    body: appendix ? filled.trimEnd() + '\n' + appendix : filled,
+    missed,
+    textless,
+    generated,
+    unresolved,
+    covered: used.size,
+    total,
+  };
+};
+
+/** The trailing section: everything the walkthrough did not account for, so the diff stays whole. */
+const renderMissed = (
+  missed: { path: string; hunks: PatchHunk[] }[],
+  textless: string[],
+  generated: string[],
+): string => {
+  if (missed.length === 0 && textless.length === 0 && generated.length === 0) {
+    return '';
+  }
+
+  const hunks = missed.reduce((count, file) => count + file.hunks.length, 0);
+  const lines = ['', '## Also changed', ''];
+  if (missed.length > 0) {
+    lines.push(
+      `${hunks} ${hunks === 1 ? 'hunk' : 'hunks'} across ${missed.length} ${missed.length === 1 ? 'file' : 'files'} the walkthrough above does not describe.`,
+      '',
+    );
+  }
+  for (const file of missed) {
+    lines.push(buildFence('```', { file: file.path, lines: hunkRange(file.hunks) ?? '' }, renderHunks(file.hunks)), '');
+  }
+  if (textless.length > 0) {
+    lines.push(`Changed with no lines to show (renamed or mode-only): ${textless.join(', ')}.`, '');
+  }
+  if (generated.length > 0) {
+    lines.push(`Generated or binary, not shown: ${generated.join(', ')}.`, '');
+  }
+
+  return lines.join('\n');
+};

package/src/walkthrough/generate.test.ts

@@ -0,0 +1,219 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import * as Progress from '@dxos/app-toolkit/Progress';
+import { Database, Filter, Ref } from '@dxos/echo';
+import { EchoTestBuilder } from '@dxos/echo-client/testing';
+import * as EffectEx from '@dxos/effect/EffectEx';
+import { PullRequest } from '@dxos/types';
+
+import { Walkthrough } from '#types';
+
+import { GENERATE_PHASES, generateWalkthrough } from './generate.ts';
+
+const DIFF = [
+  'diff --git a/src/a.ts b/src/a.ts',
+  '--- a/src/a.ts',
+  '+++ b/src/a.ts',
+  '@@ -1,1 +1,2 @@',
+  ' keep();',
+  '+added();',
+  'diff --git a/src/b.ts b/src/b.ts',
+  '--- a/src/b.ts',
+  '+++ b/src/b.ts',
+  '@@ -1,1 +1,2 @@',
+  ' header();',
+  '+extra();',
+].join('\n');
+
+/** What the model is asked to produce: prose plus an empty fence naming one file. */
+const NARRATION = ['# A change', '', 'Prose about it.', '', '```diff file=src/a.ts', '```', ''].join('\n');
+
+describe('generateWalkthrough', () => {
+  let builder: EchoTestBuilder;
+
+  beforeEach(async () => {
+    builder = await new EchoTestBuilder().open();
+  });
+
+  afterEach(async () => {
+    await builder.close();
+  });
+
+  const setup = async () => {
+    const { db, graph } = await builder.createDatabase();
+    graph.registry.add([PullRequest.PullRequest, Walkthrough.Walkthrough]);
+    const pullRequest = db.add(
+      PullRequest.make({ owner: 'dxos', repo: 'dxos', number: 1, title: 'A change', state: 'open' }),
+    );
+    await db.flush();
+
+    const phases: { message: string; current: number }[] = [];
+    const run = (options: { commit?: string; force?: boolean; narration?: string } = {}) =>
+      EffectEx.runPromise(
+        generateWalkthrough({
+          pullRequest,
+          remote: { commit: options.commit ?? 'sha-1' },
+          diff: DIFF,
+          force: options.force,
+          model: 'test-model',
+          narrate: () => Effect.succeed(options.narration ?? NARRATION),
+          report: (message, current) => phases.push({ message, current }),
+        }).pipe(Effect.provide(Database.layer(db))),
+      );
+
+    return { db, pullRequest, phases, run };
+  };
+
+  test('creates a walkthrough, filling the chunk from the patch', async () => {
+    const { run, pullRequest } = await setup();
+    const result = await run();
+
+    expect(result.generated).to.eq(true);
+    expect(result.walkthrough.commit).to.eq('sha-1');
+    expect(result.walkthrough.model).to.eq('test-model');
+    expect(result.walkthrough.pullRequest.target).to.eq(pullRequest);
+    // The fence was empty; the hunk comes from the diff, not from the model.
+    expect(result.walkthrough.body).to.contain('+added();');
+    expect(result.walkthrough.body).to.contain('@@ -1,1 +1,2 @@');
+  });
+
+  test('appends what the narration did not claim', async () => {
+    const { run } = await setup();
+    const result = await run();
+
+    expect(result.covered).to.eq(1);
+    expect(result.total).to.eq(2);
+    expect(result.walkthrough.body).to.contain('## Also changed');
+    expect(result.walkthrough.body).to.contain('+extra();');
+  });
+
+  test('returns the existing walkthrough unchanged for the same commit', async () => {
+    const { run } = await setup();
+    const first = await run();
+    const second = await run({ narration: '# Different\n' });
+
+    expect(second.generated).to.eq(false);
+    expect(second.walkthrough).to.eq(first.walkthrough);
+    expect(second.walkthrough.body).to.contain('# A change');
+    expect(second.covered).to.eq(1);
+  });
+
+  test('regenerates when forced', async () => {
+    const { run } = await setup();
+    const first = await run();
+    const second = await run({ force: true, narration: '# Rewritten\n' });
+
+    expect(second.generated).to.eq(true);
+    // The same object is replaced in place, so anything referring to it still resolves.
+    expect(second.walkthrough).to.eq(first.walkthrough);
+    expect(second.walkthrough.body).to.contain('# Rewritten');
+  });
+
+  test('regenerates when the head has moved', async () => {
+    const { run } = await setup();
+    await run();
+    const second = await run({ commit: 'sha-2', narration: '# Newer\n' });
+
+    expect(second.generated).to.eq(true);
+    expect(second.walkthrough.commit).to.eq('sha-2');
+    expect(second.walkthrough.body).to.contain('# Newer');
+  });
+
+  test('regenerates when no commit pins the existing one', async () => {
+    const { run } = await setup();
+    await run({ commit: '' });
+    const second = await run({ commit: '', narration: '# Again\n' });
+
+    // Without a head SHA the walkthrough cannot be shown to still describe the change.
+    expect(second.generated).to.eq(true);
+  });
+
+  test('stores exactly one walkthrough per pull request', async () => {
+    const { run, db } = await setup();
+    await run();
+    await run({ force: true });
+    await run({ commit: 'sha-3' });
+
+    const stored = await db.query(Filter.type(Walkthrough.Walkthrough)).run();
+    expect(stored.length).to.eq(1);
+  });
+
+  test('resolves a duplicate written by a racing generation to the newest', async () => {
+    const { db, pullRequest, run } = await setup();
+    // Two generations racing both see none and both add; the reader has to converge on one of them.
+    const older = db.add(
+      Walkthrough.make({
+        pullRequest: Ref.make(pullRequest),
+        body: 'older',
+        commit: 'sha-1',
+        generatedAt: '2026-09-14T09:00:00.000Z',
+      }),
+    );
+    const newer = db.add(
+      Walkthrough.make({
+        pullRequest: Ref.make(pullRequest),
+        body: 'newer',
+        commit: 'sha-1',
+        generatedAt: '2026-09-14T10:00:00.000Z',
+      }),
+    );
+    await db.flush();
+
+    const result = await run();
+
+    expect(result.generated).to.eq(false);
+    expect(result.walkthrough.id).to.eq(newer.id);
+    expect(result.walkthrough.id).not.to.eq(older.id);
+  });
+
+  test('orders duplicates by the instant, not by the spelling of the timestamp', async () => {
+    const { db, pullRequest, run } = await setup();
+    // `generatedAt` is an unvalidated date-time: as strings `+02:00` sorts above `Z`, as instants
+    // 08:00Z is the older of the two.
+    const offset = db.add(
+      Walkthrough.make({
+        pullRequest: Ref.make(pullRequest),
+        body: 'offset',
+        commit: 'sha-1',
+        generatedAt: '2026-09-14T10:00:00+02:00',
+      }),
+    );
+    const utc = db.add(
+      Walkthrough.make({
+        pullRequest: Ref.make(pullRequest),
+        body: 'utc',
+        commit: 'sha-1',
+        generatedAt: '2026-09-14T09:00:00.000Z',
+      }),
+    );
+    await db.flush();
+
+    const result = await run();
+
+    expect(result.walkthrough.id).to.eq(utc.id);
+    expect(result.walkthrough.id).not.to.eq(offset.id);
+  });
+
+  test('reports its phases and ends on the completion sentinel', async () => {
+    const { run, phases } = await setup();
+    await run();
+
+    expect(phases.map((phase) => phase.current)).to.deep.eq([3, 4, GENERATE_PHASES]);
+    expect(phases.at(-1)?.message).to.eq(Progress.STATUS_COMPLETE);
+  });
+
+  test('reports completion even when nothing was regenerated', async () => {
+    const { run, phases } = await setup();
+    await run();
+    phases.length = 0;
+    await run();
+
+    // A meter with no terminal stays open forever and leaves the action disabled.
+    expect(phases).to.deep.eq([{ message: Progress.STATUS_COMPLETE, current: GENERATE_PHASES }]);
+  });
+});