Proposals in native diff editors (0.2.0) bf73998c5198

// Proposals in VS Code's own diff editors (spec §6.1): each side of a

// changed file is a read-only document served from the hub, the target's

// state on the left and the projected state on the right, so a proposal

// can be read and reviewed without checking it out.

import * as vscode from "vscode";

import type * as api from "./hubapi";

import { HubAuth } from "./auth";

import { DiffRef, decodeDiffQuery, encodeDiffQuery } from "./hub";

import type { RepoRef } from "./proposals";

export const SCHEME = "oxygenhub-proposal";

/** The document URI of one side of a file in a proposal. */

export function diffUri(repo: RepoRef, number: number, side: "base" | "head", path: string): vscode.Uri {

  return vscode.Uri.from({ scheme: SCHEME, path: `/${path}`, query: encodeDiffQuery({ base: repo.base, owner: repo.owner, name: repo.name, number, side, path }) });

}

/** The proposal, side and path a document of this scheme shows. */

export function refOf(uri: vscode.Uri): DiffRef | undefined {

  return uri.scheme === SCHEME ? decodeDiffQuery(uri.query, uri.path) : undefined;

}

/** Serves both sides from the hub; a side where the file is absent is empty. */

export class ProposalContentProvider implements vscode.TextDocumentContentProvider, vscode.Disposable {

  private readonly emitter = new vscode.EventEmitter<vscode.Uri>();

  readonly onDidChange = this.emitter.event;

  private readonly open = new Set<string>();

  constructor(private readonly auth: HubAuth) {}

  async provideTextDocumentContent(uri: vscode.Uri): Promise<string> {

    const r = refOf(uri);

    if (!r) {

      return "";

    }

    this.open.add(uri.toString());

    try {

      return (await this.auth.clientFor(r.base).proposalContent(r.owner, r.name, r.number, r.side, r.path)) ?? "";

    } catch (e) {

      void vscode.window.showWarningMessage(`Oxygenhub: could not load ${r.path}: ${(e as Error).message}`);

      return "";

    }

  }

  /** Reload every open side of a proposal, after it gains changes. */

  refresh(base: string, owner: string, name: string, number: number): void {

    for (const s of this.open) {

      const r = refOf(vscode.Uri.parse(s));

      if (r && r.base === base && r.owner === owner && r.name === name && r.number === number) {

        this.emitter.fire(vscode.Uri.parse(s));

      }

    }

  }

  dispose(): void {

    this.emitter.dispose();

  }

}

function sides(repo: RepoRef, number: number, f: api.ProposalFile): { left: vscode.Uri; right: vscode.Uri } {

  return { left: diffUri(repo, number, "base", f.from ?? f.path), right: diffUri(repo, number, "head", f.path) };

}

/** One file in a diff editor. */

export async function openFileDiff(repo: RepoRef, number: number, f: api.ProposalFile): Promise<void> {

  const { left, right } = sides(repo, number, f);

  const title = `#${number} ${f.from ? `${f.from} → ${f.path}` : f.path} (${f.kind})`;

  await vscode.commands.executeCommand("vscode.diff", left, right, title, { preview: true });

}

/** Every file of a proposal in one multi-file diff editor. */

export async function openAllChanges(repo: RepoRef, p: api.Proposal, files: api.ProposalFile[]): Promise<void> {

  if (!files.length) {

    void vscode.window.showInformationMessage(`Oxygenhub: #${p.number} changes no files.`);

    return;

  }

  const resources = files.map((f) => {

    const { left, right } = sides(repo, p.number, f);

    return [right, left, right];

  });

  await vscode.commands.executeCommand("vscode.changes", `#${p.number} ${p.title}`, resources);

}

## 0.2.0

- Proposals expand to their changed files. Click one to open it in VS Code's diff editor: the target's state against the projected state, straight from the hub, no checkout needed.

- **View Changes** on a proposal (inline button, or in the detail) opens every file in one multi-file diff editor.

- Review threads appear in those diff editors on the projected side, and new comments there are anchored to the line's atom on the hub.

- Needs Oxygenhub with the proposal files and content API (2026-09-28).

- **Diffs in the editor**: expand a proposal to its files and open each in VS Code's diff editor (target against projected state), or View Changes for all of them at once, without checking out.

- **Review threads** in those diffs and on the checked-out proposal's files, anchored to atoms so they follow lines through rebases.

### 5.1 Diff editors

Each proposal row expands to the files it changes (`GET …/proposals/N/files`), with a diff icon per kind and `+added −removed`. Clicking a file opens VS Code's own diff editor; **View Changes** on the row (or in the detail) opens every file in one multi-file diff editor (`vscode.changes`). Both sides are read-only documents of the `oxygenhub-proposal` scheme, served from `GET …/proposals/N/content/{base|head}/{path}`: the target bookmark's state on the left, the projected state on the right, so a proposal can be read and reviewed without checking it out. A side where the file does not exist is empty; a rename shows its old path on the left. Open sides reload on refresh, since a proposal gains changes when its source bookmark moves.

In the diff editors (§5.1) the same controller places threads on the projected side only, at the line the hub reports for each anchored comment (the API's `line`, found by blame on the projected state), so no checkout or local `oxy` call is needed. A new thread or reply there posts the file and line; the hub anchors it to that line's atom.

  "version": "0.2.0",

        "command": "oxygenhub.openProposalFile",

        "title": "Open Proposal File Diff",

        "category": "Oxygenhub"

      },

      {

        "command": "oxygenhub.openProposalChanges",

        "title": "View Changes",

        "category": "Oxygenhub",

        "icon": "$(diff-multiple)"

      },

      {

          "command": "oxygenhub.openProposalChanges",

          "when": "view == oxygenhub.proposals && viewItem == proposal",

          "group": "inline"

        },

        {

      ],

      "commandPalette": [

        {

          "command": "oxygenhub.openProposalFile",

          "when": "false"

        }

import { ProposalContentProvider, SCHEME, openAllChanges, openFileDiff, refOf } from "./diff";

import { HubRepo, ProposalFileNode, ProposalNode, ProposalsProvider, showDetail } from "./proposals";

let content: ProposalContentProvider;

  content = new ProposalContentProvider(auth);

  context.subscriptions.push(content, vscode.workspace.registerTextDocumentContentProvider(SCHEME, content));

    vscode.commands.registerCommand("oxygenhub.openProposalFile", async (node: ProposalFileNode) => {

      await openFileDiff(node.repo, node.p.number, node.f);

      await review.loadDiff(node.repo, node.p.number).catch(() => undefined);

    }),

    vscode.commands.registerCommand("oxygenhub.openProposalChanges", (...args: unknown[]) =>

      withProposal(args, async (repo, number) => {

        try {

          const client = auth.clientFor(repo.base);

          const [p, files] = await Promise.all([client.proposal(repo.owner, repo.name, number), client.proposalFiles(repo.owner, repo.name, number)]);

          await openAllChanges(repo, p, files);

          await review.loadDiff(repo, number);

        } catch (e) {

          void vscode.window.showErrorMessage(`Oxygenhub: ${(e as Error).message}`);

        }

      }),

    ),

  refreshOpenDiffs();

/** Reload the sides of open proposal diffs, which may have gained changes. */

function refreshOpenDiffs(): void {

  const seen = new Set<string>();

  for (const doc of vscode.workspace.textDocuments) {

    const r = refOf(doc.uri);

    const key = r && `${r.base}/${r.owner}/${r.name}#${r.number}`;

    if (r && key && !seen.has(key)) {

      seen.add(key);

      content.refresh(r.base, r.owner, r.name, r.number);

    }

  }

}

  /** The files a proposal changes, target state against projected state. */

  proposalFiles(owner: string, name: string, number: number): Promise<api.ProposalFile[]> {

    return this.request("GET", `/repos/${owner}/${name}/proposals/${number}/files`);

  }

  /** A file's text on one side of a proposal; undefined when it does not exist there. */

  async proposalContent(owner: string, name: string, number: number, side: "base" | "head", path: string): Promise<string | undefined> {

    const headers: Record<string, string> = {};

    if (this.token) {

      headers.authorization = `Bearer ${this.token}`;

    }

    const res = await this.fetchImpl(`${this.base}/api/v1/repos/${owner}/${name}/proposals/${number}/content/${side}/${path.split("/").map(encodeURIComponent).join("/")}`, { headers });

    if (res.status === 404) {

      return undefined;

    }

    if (!res.ok) {

      throw new HubError(res.status, res.statusText, await res.text());

    }

    return res.text();

  }

/** Which proposal, side and file a diff document shows. */

export interface DiffRef {

  base: string;

  owner: string;

  name: string;

  number: number;

  side: "base" | "head";

  path: string;

}

/** The query string of a diff document's URI. */

export function encodeDiffQuery(r: DiffRef): string {

  return new URLSearchParams({ hub: r.base, owner: r.owner, name: r.name, number: String(r.number), side: r.side }).toString();

}

/** Parse a diff document's query and path back; undefined if it is not one. */

export function decodeDiffQuery(query: string, path: string): DiffRef | undefined {

  const q = new URLSearchParams(query);

  const number = Number(q.get("number"));

  const side = q.get("side");

  const [base, owner, name] = [q.get("hub"), q.get("owner"), q.get("name")];

  if (!base || !owner || !name || !Number.isInteger(number) || number < 1 || (side !== "base" && side !== "head")) {

    return undefined;

  }

  return { base, owner, name, number, side, path: path.replace(/^\/+/, "") };

}

  line?: number | null;

export type ProposalFile = {

  added: number;

  from?: string | null;

  kind: string;

  path: string;

  removed: number;

};

/** Just enough to name a repository on a hub. */

export type RepoRef = Pick<HubRepo, "base" | "owner" | "name">;

type Node =

  | { kind: "repo"; repo: HubRepo }

  | { kind: "bucket"; repo: HubRepo; label: string; items: api.Proposal[] }

  | { kind: "proposal"; repo: HubRepo; p: api.Proposal }

  | { kind: "file"; repo: HubRepo; p: api.Proposal; f: api.ProposalFile };

const FILE_ICONS: Record<string, string> = { added: "diff-added", removed: "diff-removed", renamed: "diff-renamed", modified: "diff-modified" };

  private files = new Map<string, api.ProposalFile[]>();

    this.files.clear();

  /** The files a proposal changes, cached until the next refresh. */

  async filesOf(repo: HubRepo, p: api.Proposal): Promise<api.ProposalFile[]> {

    const key = `${repo.base}/${repo.owner}/${repo.name}#${p.number}`;

    const hit = this.files.get(key);

    if (hit) {

      return hit;

    }

    const list = await this.auth.clientFor(repo.base).proposalFiles(repo.owner, repo.name, p.number);

    this.files.set(key, list);

    return list;

  }

        const item = new vscode.TreeItem(`#${p.number} ${p.title}`, vscode.TreeItemCollapsibleState.Collapsed);

      case "file": {

        const f = node.f;

        const slash = f.path.lastIndexOf("/");

        const item = new vscode.TreeItem(f.path.slice(slash + 1), vscode.TreeItemCollapsibleState.None);

        const dir = slash > 0 ? f.path.slice(0, slash) : "";

        item.description = [dir, f.from ? `from ${f.from}` : "", f.added || f.removed ? `+${f.added} −${f.removed}` : f.kind].filter(Boolean).join(" · ");

        item.tooltip = `${f.path} (${f.kind})`;

        item.iconPath = new vscode.ThemeIcon(FILE_ICONS[f.kind] ?? "diff");

        item.contextValue = "proposalFile";

        item.command = { title: "Open Diff", command: "oxygenhub.openProposalFile", arguments: [node] };

        return item;

      }

    if (node.kind === "proposal") {

      try {

        const files = await this.filesOf(node.repo, node.p);

        return files.map((f) => ({ kind: "file", repo: node.repo, p: node.p, f }));

      } catch (e) {

        void vscode.window.showWarningMessage(`Oxygenhub: ${(e as Error).message}`);

      }

    }

export type ProposalFileNode = Extract<Node, { kind: "file" }>;

  <p><a href="${url}">Open on hub</a> · <a href="command:oxygenhub.openProposalChanges?${arg}">View changes</a> · <a href="command:oxygenhub.checkoutProposal?${arg}">Check out</a> · <a href="command:oxygenhub.review?${arg}">Review</a> · <a href="command:oxygenhub.sealApproval?${arg}">Seal approval</a> · <a href="command:oxygenhub.land?${arg}">Land</a></p>

import type { HubRepo, RepoRef } from "./proposals";

import { diffUri, refOf } from "./diff";

  /** Threads in diff editors, per proposal (`base/owner/name#n`). */

  private readonly diffThreads = new Map<string, vscode.CommentThread[]>();

      provideCommentingRanges: (document) => {

        const whole = [new vscode.Range(0, 0, Math.max(0, document.lineCount - 1), 0)];

        // In a proposal's diff, only the projected side takes comments.

        const r = refOf(document.uri);

        if (r) {

          return r.side === "head" ? whole : [];

        }

        return this.active && document.uri.fsPath.startsWith(this.active.repo.handle.root) ? whole : [];

      },

  /**

   * Show a proposal's threads in its diff documents: every anchored

   * comment on the projected side, at the line the hub places it.

   */

  async loadDiff(repo: RepoRef, number: number): Promise<void> {

    const key = `${repo.base}/${repo.owner}/${repo.name}#${number}`;

    this.diffThreads.get(key)?.forEach((t) => t.dispose());

    const comments = await this.auth.clientFor(repo.base).proposalComments(repo.owner, repo.name, number);

    const byLine = new Map<string, api.Comment[]>();

    for (const c of comments) {

      if (c.path && c.line) {

        const k = `${c.path}\n${c.line}`;

        byLine.set(k, [...(byLine.get(k) ?? []), c]);

      }

    }

    const threads: vscode.CommentThread[] = [];

    for (const [k, cs] of byLine) {

      const [path, line] = k.split("\n");

      const thread = this.controller.createCommentThread(diffUri(repo, number, "head", path), new vscode.Range(Number(line) - 1, 0, Number(line) - 1, 0), cs.map(toComment));

      thread.label = cs.every((c) => c.resolved) ? "resolved" : "review";

      thread.state = cs.every((c) => c.resolved) ? vscode.CommentThreadState.Resolved : vscode.CommentThreadState.Unresolved;

      thread.collapsibleState = vscode.CommentThreadCollapsibleState.Expanded;

      threads.push(thread);

    }

    this.diffThreads.set(key, threads);

  }

    const r = refOf(reply.thread.uri);

    if (r) {

      const line = (reply.thread.range?.start.line ?? 0) + 1;

      const repo: RepoRef = { base: r.base, owner: r.owner, name: r.name };

      try {

        await postLineComment(this.auth, repo, r.number, r.path, line, reply.text);

      } catch (e) {

        void vscode.window.showErrorMessage(`Oxygenhub: ${(e as Error).message}`);

        return;

      }

      // A new thread from the gutter is replaced by the hub's copy.

      if (!reply.thread.comments.length) {

        reply.thread.dispose();

      }

      await this.loadDiff(repo, r.number);

      return;

    }

    this.diffThreads.forEach((ts) => ts.forEach((t) => t.dispose()));

    this.diffThreads.clear();

async function postLineComment(auth: HubAuth, repo: RepoRef, number: number, path: string, line: number, body: string): Promise<void> {

import { HubClient, HubError, encodeDiffQuery, decodeDiffQuery } from "../out/hub.mjs";

    writeFileSync(join(work, "src/a.txt"), "a\nA\n");

    // The proposal's files and both sides, as the diff editors fetch them.

    const files = await client.proposalFiles("andy", "demo", 1);

    assert.deepEqual(

      files.map((f) => [f.path, f.kind]),

      [

        ["src/a.txt", "modified"],

        ["src/b.txt", "added"],

      ],

    );

    assert.equal(await client.proposalContent("andy", "demo", 1, "base", "src/a.txt"), "a\n");

    assert.equal(await client.proposalContent("andy", "demo", 1, "head", "src/a.txt"), "a\nA\n");

    assert.equal(await client.proposalContent("andy", "demo", 1, "base", "src/b.txt"), undefined, "absent on the target side");

    // A review comment from the diff comes back on its line.

    const c = await client.commentProposal("andy", "demo", 1, "why?", "src/a.txt", 2);

    assert.equal(c.line, 2);

    const comments = await client.proposalComments("andy", "demo", 1);

    assert.equal(comments[0].line, 2);

test("diff document queries round trip", () => {

  const ref = { base: "https://earth.example:7343", owner: "andy", name: "demo", number: 7, side: "head", path: "src/dir with space/a.txt" };

  const back = decodeDiffQuery(encodeDiffQuery(ref), "/" + ref.path);

  assert.deepEqual(back, ref);

  assert.equal(decodeDiffQuery("hub=x&owner=a&name=b&number=0&side=head", "/p"), undefined, "number must be positive");

  assert.equal(decodeDiffQuery("hub=x&owner=a&name=b&number=3&side=left", "/p"), undefined, "side is base or head");

  assert.equal(decodeDiffQuery("owner=a&name=b&number=3&side=head", "/p"), undefined, "the hub is required");

});