@dxos/plugin-github 0.7.4 → 0.13.0

package/src/walkthrough/generate.ts

@@ -0,0 +1,248 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import * as Progress from '@dxos/app-toolkit/Progress';
+import { Database, Filter, Obj, Ref } from '@dxos/echo';
+import { PullRequest } from '@dxos/types';
+
+import { Walkthrough } from '#types';
+
+import { fillWalkthrough } from './fill.ts';
+import { isGeneratedFile } from './generated.ts';
+import { spaceHeadings } from './headings.ts';
+import { parsePatch } from './patch.ts';
+import {
+  CHAPTER_SYSTEM_PROMPT,
+  DEFAULT_CHAPTER_THRESHOLD_CHARS,
+  PLANNER_SYSTEM_PROMPT,
+  assembleWalkthrough,
+  buildChapterPrompt,
+  buildPlannerPrompt,
+  chapterDiff,
+  parsePlan,
+} from './plan.ts';
+import { SYSTEM_PROMPT, buildPrompt } from './prompt.ts';
+
+/** What the pull request looks like on GitHub right now, as against the local mirror of it. */
+export type RemoteFacts = {
+  title?: string;
+  description?: string;
+  baseBranch?: string;
+  headBranch?: string;
+  /** Head SHA. Absent means the walkthrough cannot be pinned to a commit, so it is always stale. */
+  commit?: string;
+};
+
+export type GenerateOptions<R = never> = {
+  pullRequest: PullRequest.PullRequest;
+  remote: RemoteFacts;
+  /** The whole unified diff, which the chunks are filled from. */
+  diff: string;
+  /** Regenerate even where a walkthrough for this head already exists. */
+  force?: boolean;
+  /** Identifier recorded on the result, so a regression can be attributed after the default moves. */
+  model: string;
+  /**
+   * Runs the model over the prompt. Injected so the decision logic can be tested without one, and
+   * generic in its requirement so the model service it needs is DECLARED by the caller rather than
+   * quietly dropped — a requirement erased here is a defect at the first real invocation.
+   */
+  narrate: (prompt: string) => Effect.Effect<string, never, R>;
+  /** Phase reporter; `current` counts against {@link GENERATE_PHASES}. */
+  report?: (message: string, current: number) => void;
+  /**
+   * Diff size past which the walkthrough is planned into chapters and narrated a chapter at a time.
+   * Zero forces the two-stage path; `Infinity` forces the one-shot path.
+   */
+  chapterThresholdChars?: number;
+};
+
+export type GenerateResult = {
+  walkthrough: Walkthrough.Walkthrough;
+  /** How the body was written: one prompt, or a plan plus a prompt per chapter. */
+  strategy?: 'one-shot' | 'chaptered';
+  /** Whether the model ran, as against an existing walkthrough being returned unchanged. */
+  generated: boolean;
+  covered: number;
+  total: number;
+};
+
+/** Phases a caller's progress meter counts, so it is determinate rather than a spinner. */
+export const GENERATE_PHASES = 5;
+
+/**
+ * Decides whether to regenerate, runs the model, fills the chunks, and stores the result.
+ *
+ * Split from the operation handler so the part with the decisions in it can be tested against a real
+ * database without a network or a model: what the handler adds is two HTTP calls.
+ */
+export const generateWalkthrough = <R = never>({
+  pullRequest,
+  remote,
+  diff,
+  force,
+  model,
+  narrate,
+  report = () => {},
+  chapterThresholdChars = DEFAULT_CHAPTER_THRESHOLD_CHARS,
+}: GenerateOptions<R>): Effect.Effect<GenerateResult, never, Database.Service | R> =>
+  Effect.gen(function* () {
+    const existing = yield* findWalkthrough(pullRequest);
+
+    // Regenerating against the same head cannot change the answer, so it is only work.
+    if (existing && !force && remote.commit && !Walkthrough.isStale(existing, remote.commit)) {
+      report(Progress.STATUS_COMPLETE, GENERATE_PHASES);
+      return {
+        walkthrough: existing,
+        generated: false,
+        covered: existing.covered ?? 0,
+        total: existing.total ?? 0,
+      };
+    }
+
+    report('Writing the walkthrough', 3);
+    const facts = {
+      owner: pullRequest.owner,
+      repo: pullRequest.repo,
+      number: pullRequest.number,
+      title: remote.title ?? pullRequest.title,
+      description: remote.description ?? pullRequest.description,
+      baseBranch: remote.baseBranch ?? pullRequest.baseBranch,
+      headBranch: remote.headBranch ?? pullRequest.headBranch,
+    };
+    const chaptered =
+      diff.length > chapterThresholdChars ? yield* narrateChapters(facts, diff, narrate, report) : undefined;
+    const narration = chaptered ?? (yield* narrate(`${SYSTEM_PROMPT}\n\n---\n\n${buildPrompt({ ...facts, diff })}`));
+
+    report('Filling the chunks', 4);
+    const filled = fillWalkthrough(narration, diff);
+    const walkthrough = yield* upsert(existing, {
+      pullRequest: Ref.make(pullRequest),
+      title: Walkthrough.makeTitle(pullRequest, remote.title ?? pullRequest.title),
+      body: spaceHeadings(filled.body),
+      commit: remote.commit ?? '',
+      generatedAt: new Date().toISOString(),
+      model,
+      covered: filled.covered,
+      total: filled.total,
+    });
+
+    report(Progress.STATUS_COMPLETE, GENERATE_PHASES);
+    return {
+      walkthrough,
+      strategy: chaptered ? ('chaptered' as const) : ('one-shot' as const),
+      generated: true,
+      covered: filled.covered,
+      total: filled.total,
+    };
+  });
+
+/**
+ * Plans the chapters, then narrates each one against its own files.
+ *
+ * Returns undefined when the plan cannot be read, so the caller falls back to one prompt rather
+ * than failing: a walkthrough of part of the change beats no walkthrough.
+ */
+const narrateChapters = <R>(
+  facts: Parameters<typeof buildPlannerPrompt>[0],
+  diff: string,
+  narrate: (prompt: string) => Effect.Effect<string, never, R>,
+  report: (message: string, current: number) => void,
+): Effect.Effect<string | undefined, never, R> =>
+  Effect.gen(function* () {
+    const files = parsePatch(diff).filter((file) => !isGeneratedFile(file));
+    const planned = yield* narrate(`${PLANNER_SYSTEM_PROMPT}\n\n---\n\n${buildPlannerPrompt(facts, diff)}`);
+    const plan = parsePlan(
+      planned,
+      files.map((file) => file.path),
+    );
+    if (!plan) {
+      return undefined;
+    }
+
+    const chapters: string[] = [];
+    for (const chapter of plan.chapters) {
+      report(`Writing "${chapter.title}"`, 3);
+      // Serial rather than concurrent: a chapter is written against a document the reader meets in
+      // order, and the model's own rate limit is the binding constraint on a large change anyway.
+      const body = yield* narrate(
+        `${CHAPTER_SYSTEM_PROMPT}\n\n---\n\n${buildChapterPrompt(plan, chapter, chapterDiff(files, chapter))}`,
+      );
+      chapters.push(body);
+    }
+
+    return assembleWalkthrough(plan, chapters);
+  });
+
+/** The walkthrough already written for this pull request, if any. */
+export const findWalkthrough = (
+  pullRequest: PullRequest.PullRequest,
+): Effect.Effect<Walkthrough.Walkthrough | undefined, never, Database.Service> =>
+  Database.query(Filter.type(Walkthrough.Walkthrough, { pullRequest: Ref.make(pullRequest) })).run.pipe(
+    // Filtered by the ref rather than by loading every walkthrough and comparing: a space holds one
+    // per reviewed pull request, which is not a handful.
+    Effect.map(newestWalkthrough),
+    Effect.orDie,
+  );
+
+/**
+ * The newest of however many were written, ties broken by id.
+ *
+ * Two generations racing on one pull request both see none and both add: the check and the write
+ * are separate steps, and ECHO has neither a uniqueness constraint nor an atomic upsert to close
+ * that. Picking deterministically makes the duplicate inert instead — every reader lands on the
+ * same object, and the next regeneration updates that one in place rather than forking again. The
+ * loser stays in the space; removing it from a read path would delete another client's object.
+ */
+export const newestWalkthrough = (
+  walkthroughs: readonly Walkthrough.Walkthrough[],
+): Walkthrough.Walkthrough | undefined =>
+  walkthroughs.reduce<Walkthrough.Walkthrough | undefined>((newest, walkthrough) => {
+    if (!newest) {
+      return walkthrough;
+    }
+    const left = generatedTime(walkthrough);
+    const right = generatedTime(newest);
+    if (left !== right) {
+      return left > right ? walkthrough : newest;
+    }
+
+    // The id is a ULID, so it is fixed width and orders the same on every peer.
+    return walkthrough.id > newest.id ? walkthrough : newest;
+  }, undefined);
+
+/**
+ * Parsed rather than compared as a string: `generatedAt` is an unvalidated date-time, so a value
+ * written by anything but this code can carry an offset (`+02:00`) that sorts against a `Z` value
+ * the wrong way round. An unparseable or absent one sorts oldest.
+ */
+const generatedTime = (walkthrough: Walkthrough.Walkthrough): number => {
+  const parsed = Date.parse(walkthrough.generatedAt ?? '');
+  return Number.isNaN(parsed) ? Number.NEGATIVE_INFINITY : parsed;
+};
+
+/** Replaces the body in place where one exists, so links to the walkthrough survive regeneration. */
+const upsert = (
+  existing: Walkthrough.Walkthrough | undefined,
+  props: Obj.MakeProps<typeof Walkthrough.Walkthrough>,
+): Effect.Effect<Walkthrough.Walkthrough, never, Database.Service> =>
+  Effect.gen(function* () {
+    if (!existing) {
+      return yield* Database.add(Walkthrough.make(props));
+    }
+
+    // One notification for the whole replacement, rather than six — a subscriber re-rendering the
+    // document between the body and the commit would show one against the other.
+    return Obj.update(existing, (existing) => {
+      existing.title = props.title;
+      existing.body = props.body;
+      existing.commit = props.commit;
+      existing.generatedAt = props.generatedAt;
+      existing.model = props.model;
+      existing.covered = props.covered;
+      existing.total = props.total;
+    });
+  });

package/src/walkthrough/generated.test.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { isBinaryPatch, isGeneratedFile, isGeneratedPath } from './generated.ts';
+
+describe('isGeneratedPath', () => {
+  test.each([
+    'pnpm-lock.yaml',
+    'apps/site/package-lock.json',
+    'yarn.lock',
+    'Cargo.lock',
+    'go.sum',
+    'packages/core/dist/index.js',
+    'packages/core/build/bundle.css',
+    'coverage/lcov-report/index.html',
+    'vendor/lib/thing.ts',
+    'src/__snapshots__/render.test.ts',
+    'public/app.min.js',
+    'public/app.min.css',
+    'dist-info/bundle.js.map',
+    'src/render.test.ts.snap',
+    'src/types/index.d.ts',
+    'src/proto/service_pb.ts',
+    'src/proto/service.pb.go',
+    'src/proto/service_pb2.py',
+    'src/schema.gen.ts',
+    'src/theme.generated.css',
+    'assets/logo.png',
+    'assets/font.woff2',
+    'fixtures/archive.tar.gz',
+    'bin/tool.wasm',
+    '.changeset/wild-pans-argue.md',
+    'packages/thing/.changeset/quiet-moons.md',
+  ])('%s is generated', (path) => {
+    expect(isGeneratedPath(path)).to.be.true;
+  });
+
+  test.each([
+    'src/index.ts',
+    'packages/core/src/query/compile.ts',
+    'docs/DESIGN.md',
+    'src/components/Button.tsx',
+    // Near misses: a file is not generated because its name contains a generated word.
+    'src/distribution.ts',
+    'src/generated-ids.ts',
+    'src/build-plan.ts',
+    'scripts/lockfile-audit.ts',
+  ])('%s is not generated', (path) => {
+    expect(isGeneratedPath(path)).to.be.false;
+  });
+});
+
+describe('isBinaryPatch', () => {
+  test('reads git’s own markers', () => {
+    expect(isBinaryPatch(['Binary files a/x.dat and b/x.dat differ'])).to.be.true;
+    expect(isBinaryPatch(['GIT binary patch', 'literal 1234'])).to.be.true;
+    expect(isBinaryPatch(['index 111..222 100644', '--- a/src/a.ts', '+++ b/src/a.ts'])).to.be.false;
+  });
+});
+
+describe('isGeneratedFile', () => {
+  test('catches a binary the extension does not announce', () => {
+    // A file with no extension at all, which only the patch shape gives away.
+    expect(isGeneratedFile({ path: 'fixtures/corpus', preamble: ['Binary files a/x and b/x differ'] })).to.be.true;
+    expect(isGeneratedFile({ path: 'src/index.ts', preamble: ['index 111..222 100644'] })).to.be.false;
+  });
+});

package/src/walkthrough/generated.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Files a reviewer does not read, and a walkthrough should not spend prose or a fence on: machine
+ * output, vendored blobs, and anything whose diff is a consequence of another file in the same
+ * change.
+ *
+ * Detection is by path and by patch shape rather than by a `.gitattributes` lookup, because the
+ * walkthrough only ever has the patch.
+ */
+
+/** Lockfiles: the largest hunk in most pull requests and the one nobody reads. */
+const LOCKFILES = [
+  'pnpm-lock.yaml',
+  'package-lock.json',
+  'yarn.lock',
+  'bun.lockb',
+  'npm-shrinkwrap.json',
+  'Cargo.lock',
+  'poetry.lock',
+  'composer.lock',
+  'Gemfile.lock',
+  'go.sum',
+  'flake.lock',
+  'uv.lock',
+];
+
+/** Directories whose contents are built, vendored or cached rather than written. */
+const GENERATED_DIRECTORIES = /(^|\/)(dist|build|out|coverage|node_modules|vendor|__snapshots__|\.turbo)\//;
+
+/** Suffixes that are compiled, minified, generated from a schema, or not text at all. */
+const GENERATED_SUFFIX =
+  /(\.min\.(js|css)|\.map|\.snap|\.d\.ts|[._-]pb\.(ts|js)|\.pb\.go|_pb2\.py|\.gen\.(ts|js|go)|\.generated\.[a-z]+)$/i;
+
+/** Binary by extension. A patch shows these as "Binary files … differ", with nothing to read. */
+const BINARY_SUFFIX =
+  /\.(png|jpe?g|gif|webp|avif|ico|icns|bmp|tiff?|svgz|pdf|woff2?|ttf|otf|eot|zip|gz|tgz|bz2|xz|7z|rar|wasm|so|dylib|dll|exe|bin|dat|db|sqlite3?|mp[34]|mov|mp4|webm|wav|ogg|jar|class|pyc|node)$/i;
+
+/**
+ * Whether a path is machine-written or unreadable.
+ *
+ * `.changeset/` entries count: the changeset is a consequence of the change the walkthrough already
+ * describes, and a section about it tells the reader nothing the rest of the document did not.
+ */
+export const isGeneratedPath = (path: string): boolean => {
+  const name = path.split('/').pop() ?? path;
+  return (
+    LOCKFILES.includes(name) ||
+    GENERATED_DIRECTORIES.test(path) ||
+    GENERATED_SUFFIX.test(path) ||
+    BINARY_SUFFIX.test(path) ||
+    path.startsWith('.changeset/') ||
+    path.includes('/.changeset/')
+  );
+};
+
+/** A file git could not diff as text, whatever its extension says. */
+export const isBinaryPatch = (preamble: readonly string[]): boolean =>
+  preamble.some((line) => line.startsWith('Binary files ') || line.startsWith('GIT binary patch'));
+
+/**
+ * Whether this file is one the walkthrough should leave alone.
+ *
+ * A hunk count of zero is NOT generated on its own: a rename or a mode change is still a change a
+ * reviewer has to know about, and {@link fillWalkthrough} reports it separately.
+ */
+export const isGeneratedFile = (file: { path: string; preamble: readonly string[] }): boolean =>
+  isGeneratedPath(file.path) || isBinaryPatch(file.preamble);

package/src/walkthrough/headings.test.ts

@@ -0,0 +1,40 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, expect, test } from 'vitest';
+
+import { spaceHeadings } from './headings.ts';
+
+describe('spaceHeadings', () => {
+  test('separates a heading from the paragraph above it', () => {
+    expect(spaceHeadings('First.\n## Schema: Task gains attachments\nBody.')).to.equal(
+      'First.\n\n## Schema: Task gains attachments\nBody.',
+    );
+  });
+
+  test('leaves an already separated heading and a leading heading alone', () => {
+    const markdown = '# Title\n\nWhy.\n\n## One\n\nFirst.\n';
+    expect(spaceHeadings(markdown)).to.equal(markdown);
+  });
+
+  test('ignores hash lines inside a code fence', () => {
+    const markdown = 'Prose.\n\n```diff file=a.sh\n+echo\n# a shell comment\n```\n';
+    expect(spaceHeadings(markdown)).to.equal(markdown);
+  });
+
+  test('a fence line with an info string does not close the fence', () => {
+    const markdown = 'Prose.\n\n```md\nText.\n```ts\n# still code\n```\nAfter.\n## Next\n';
+    expect(spaceHeadings(markdown)).to.equal('Prose.\n\n```md\nText.\n```ts\n# still code\n```\nAfter.\n\n## Next\n');
+  });
+
+  test('reads CRLF lines, and keeps their line endings', () => {
+    const markdown = 'Prose.\r\n\r\n```\r\ncode\r\n```\r\nAfter.\r\n## Next\r\n';
+    expect(spaceHeadings(markdown)).to.equal('Prose.\r\n\r\n```\r\ncode\r\n```\r\nAfter.\r\n\r\n## Next\r\n');
+  });
+
+  test('does not treat a hashtag as a heading', () => {
+    const markdown = 'Prose.\n#hashtag';
+    expect(spaceHeadings(markdown)).to.equal(markdown);
+  });
+});

package/src/walkthrough/headings.ts

@@ -0,0 +1,39 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+const FENCE = /^\s{0,3}(`{3,}|~{3,})/;
+/** A closing fence carries nothing after its marker: a line with an info string only opens one. */
+const CLOSING_FENCE = /^\s{0,3}(`{3,}|~{3,})[ \t]*$/;
+const HEADING = /^\s{0,3}#{1,6}(\s|$)/;
+
+/**
+ * Puts a blank line before every heading outside a code fence.
+ *
+ * A heading may legally interrupt a paragraph, so the model and the chapter join both emit one on
+ * the very next line — which the walkthrough's source-level editor shows flush against the prose.
+ */
+export const spaceHeadings = (markdown: string): string => {
+  const lines = markdown.split('\n');
+  const result: string[] = [];
+  let fence: string | undefined;
+  for (const line of lines) {
+    // Split on `\n` alone, so a CRLF line keeps its `\r`: matched without it, written back with it.
+    const crlf = line.endsWith('\r');
+    const text = crlf ? line.slice(0, -1) : line;
+    const marker = text.match(FENCE)?.[1];
+    if (fence) {
+      const closer = text.match(CLOSING_FENCE)?.[1];
+      if (closer && closer[0] === fence[0] && closer.length >= fence.length) {
+        fence = undefined;
+      }
+    } else if (marker) {
+      fence = marker;
+    } else if (HEADING.test(text) && result.length > 0 && result[result.length - 1].trim() !== '') {
+      result.push(crlf ? '\r' : '');
+    }
+    result.push(line);
+  }
+
+  return result.join('\n');
+};

package/src/walkthrough/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './fill.ts';
+export * from './generate.ts';
+export * from './generated.ts';
+export * from './headings.ts';
+export * from './patch.ts';
+export * from './plan.ts';
+export * from './prompt.ts';
+export * from './score.ts';

package/src/walkthrough/patch.ts

@@ -0,0 +1,154 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/** A `@@` hunk, kept as the verbatim lines git emitted so filling a chunk is lossless. */
+export type PatchHunk = {
+  /** The `@@ -a,b +c,d @@ section` line. */
+  header: string;
+  /** Body lines (context, additions, removals), without the header. */
+  lines: string[];
+  /** 1-based inclusive span in the file AFTER the change; `afterEnd < afterStart` for a pure removal. */
+  afterStart: number;
+  afterEnd: number;
+  /** The same span in the file BEFORE it, which is all a pure removal has. */
+  beforeStart: number;
+  beforeEnd: number;
+  added: number;
+  removed: number;
+};
+
+export type PatchFile = {
+  /** Path after the change, or the pre-image path when the file was deleted. */
+  path: string;
+  /** Headers git emitted before the first hunk (`diff --git`, `index`, `---`, `+++`). */
+  preamble: string[];
+  hunks: PatchHunk[];
+  added: number;
+  removed: number;
+};
+
+const FILE_HEADER = /^diff --git a\/(.+?) b\/(.+)$/;
+const HUNK_HEADER = /^@@+\s+-(\d+)(?:,(\d+))?\s+\+(\d+)(?:,(\d+))?\s+@@/;
+
+/**
+ * Splits a multi-file unified diff — what `GET /repos/…/pulls/N` returns under the `diff` media type
+ * — into files and hunks. Hunk bodies are carried verbatim rather than re-derived, so a chunk filled
+ * from one is byte-identical to what git produced.
+ */
+export const parsePatch = (patch: string): PatchFile[] => {
+  const files: PatchFile[] = [];
+  let file: PatchFile | undefined;
+  let hunk: PatchHunk | undefined;
+
+  for (const raw of patch.split('\n')) {
+    // A patch saved or served with CRLF keeps its carriage returns, and every match below is
+    // anchored: left in place they make the whole parse return nothing at all.
+    const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+    const header = FILE_HEADER.exec(line);
+    if (header) {
+      // `b/` is the post-image path and is `/dev/null` only in the `+++` line, never here.
+      file = { path: header[2], preamble: [line], hunks: [], added: 0, removed: 0 };
+      files.push(file);
+      hunk = undefined;
+      continue;
+    }
+    if (!file) {
+      continue;
+    }
+
+    const hunkHeader = HUNK_HEADER.exec(line);
+    if (hunkHeader) {
+      const beforeStart = Number(hunkHeader[1]);
+      const beforeCount = hunkHeader[2] === undefined ? 1 : Number(hunkHeader[2]);
+      const afterStart = Number(hunkHeader[3]);
+      const afterCount = hunkHeader[4] === undefined ? 1 : Number(hunkHeader[4]);
+      hunk = {
+        header: line,
+        lines: [],
+        afterStart,
+        afterEnd: afterStart + afterCount - 1,
+        beforeStart,
+        beforeEnd: beforeStart + beforeCount - 1,
+        added: 0,
+        removed: 0,
+      };
+      file.hunks.push(hunk);
+      continue;
+    }
+
+    if (!hunk) {
+      file.preamble.push(line);
+      continue;
+    }
+
+    // `` annotates the preceding line and is not a line of either version.
+    if (line.startsWith('\\')) {
+      hunk.lines.push(line);
+      continue;
+    }
+    if (line.startsWith('+')) {
+      hunk.added++;
+      file.added++;
+    } else if (line.startsWith('-')) {
+      hunk.removed++;
+      file.removed++;
+    }
+    hunk.lines.push(line);
+  }
+
+  // Only the LAST hunk of the LAST file can carry the transport's trailing newline, and only one of
+  // them: a blank line anywhere else is context the chunk has to keep showing.
+  const trailing = files.at(-1)?.hunks.at(-1);
+  if (trailing?.lines.at(-1) === '') {
+    trailing.lines.pop();
+  }
+
+  // A patch may name one path twice (a rename reported as delete-then-add, a malformed paste). Their
+  // hunks belong to one file, or the second silently hides the first from every fence.
+  const merged = new Map<string, PatchFile>();
+  for (const file of files) {
+    const existing = merged.get(file.path);
+    if (existing) {
+      existing.hunks.push(...file.hunks);
+      existing.added += file.added;
+      existing.removed += file.removed;
+    } else {
+      merged.set(file.path, file);
+    }
+  }
+
+  return [...merged.values()];
+};
+
+/** The hunk text a diff fence holds: the `@@` header and its body, as git wrote them. */
+export const renderHunks = (hunks: PatchHunk[]): string =>
+  hunks.map((hunk) => [hunk.header, ...hunk.lines].join('\n')).join('\n');
+
+/**
+ * Whether a hunk shows any of `[start, end]` of the post-change file.
+ *
+ * A pure removal spans nothing after the change (`afterEnd === afterStart - 1`), so it is treated as
+ * occupying the single position the lines were removed from — otherwise no range could ever select
+ * it, including the one this module's own {@link hunkRange} reports for it.
+ */
+export const hunkOverlaps = (hunk: PatchHunk, start: number, end: number): boolean =>
+  hunk.afterStart <= end && Math.max(hunk.afterEnd, hunk.afterStart) >= start;
+
+/**
+ * The span a set of hunks covers, for a fence's `lines=` attribute.
+ *
+ * Measured after the change, except where nothing survives it: a deleted file's post-image is empty
+ * and would otherwise read as `Lines 0`, so its range is quoted from the pre-image instead.
+ */
+export const hunkRange = (hunks: PatchHunk[]): string | undefined => {
+  if (hunks.length === 0) {
+    return undefined;
+  }
+  const survives = hunks.some((hunk) => hunk.afterEnd >= hunk.afterStart);
+  const start = Math.min(...hunks.map((hunk) => (survives ? hunk.afterStart : hunk.beforeStart)));
+  // `afterStart` for a pure removal, as `hunkOverlaps` does: its `afterEnd` is one BELOW its start,
+  // so a set mixing one with a live hunk would end the range before the removal it contains.
+  const end = Math.max(...hunks.map((hunk) => (survives ? Math.max(hunk.afterEnd, hunk.afterStart) : hunk.beforeEnd)));
+  return start >= end ? `${start}` : `${start}-${end}`;
+};