feat: a Diffusion view, what each repository takes from and diffuses to (closes #5) d21a85954a34

// The Diffusion view (oxygenhub-vscode#5, oxygenhub docs/diffusion.md): for

// each repository, the subrepos it takes from and the repositories it

// diffuses to, each with the hub's pill in words and its open bump.

import * as vscode from "vscode";

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

import { HubAuth } from "./auth";

import { hubUrl } from "./hub";

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

import { look, pinDescription, pinLabel, pinTooltip, tone } from "./diffusionview";

type Side = "takes" | "gives";

type Node =

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

  | { kind: "side"; repo: HubRepo; side: Side; pins: api.DiffusionPin[] }

  | { kind: "pin"; repo: HubRepo; side: Side; pin: api.DiffusionPin }

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

export type DiffusionPinNode = Extract<Node, { kind: "pin" }>;

export class DiffusionProvider implements vscode.TreeDataProvider<Node> {

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

  readonly onDidChangeTreeData = this.emitter.event;

  constructor(

    private readonly repos: () => Promise<HubRepo[]>,

    private readonly auth: HubAuth,

  ) {}

  refresh(): void {

    this.emitter.fire();

  }

  getTreeItem(node: Node): vscode.TreeItem {

    switch (node.kind) {

      case "repo": {

        const item = new vscode.TreeItem(`${node.repo.owner}/${node.repo.name}`, vscode.TreeItemCollapsibleState.Expanded);

        item.iconPath = new vscode.ThemeIcon("repo");

        item.contextValue = "diffusionRepo";

        return item;

      }

      case "side": {

        const item = new vscode.TreeItem(node.side === "takes" ? "Takes from" : "Diffuses to", vscode.TreeItemCollapsibleState.Expanded);

        item.description = String(node.pins.length);

        item.iconPath = new vscode.ThemeIcon(node.side === "takes" ? "arrow-down" : "arrow-up");

        return item;

      }

      case "pin": {

        const t = tone(node.pin);

        const l = look(t);

        const item = new vscode.TreeItem(pinLabel(node.pin, node.side), vscode.TreeItemCollapsibleState.None);

        item.description = pinDescription(node.pin);

        item.iconPath = new vscode.ThemeIcon(l.icon, new vscode.ThemeColor(l.color));

        item.tooltip = new vscode.MarkdownString(pinTooltip(node.pin));

        item.contextValue = node.pin.bump !== null && node.pin.bump !== undefined ? "diffusionPinBump" : "diffusionPin";

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

        return item;

      }

      case "none": {

        const item = new vscode.TreeItem("Neither pins nor is pinned by a repository on the hub", vscode.TreeItemCollapsibleState.None);

        item.iconPath = new vscode.ThemeIcon("info");

        return item;

      }

    }

  }

  async getChildren(node?: Node): Promise<Node[]> {

    if (!node) {

      return (await this.repos()).map((repo) => ({ kind: "repo", repo }));

    }

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

      try {

        const d = await this.auth.clientFor(node.repo.base).diffusion(node.repo.owner, node.repo.name);

        const out: Node[] = [];

        if (d.takes_from.length > 0) {

          out.push({ kind: "side", repo: node.repo, side: "takes", pins: d.takes_from });

        }

        if (d.diffuses_to.length > 0) {

          out.push({ kind: "side", repo: node.repo, side: "gives", pins: d.diffuses_to });

        }

        return out.length > 0 ? out : [{ kind: "none", repo: node.repo }];

      } catch (e) {

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

        return [];

      }

    }

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

      return node.pins.map((pin) => ({ kind: "pin", repo: node.repo, side: node.side, pin }));

    }

    return [];

  }

}

/** Where a row leads on the hub: its open bump, else the other repository. */

export function pinUrl(node: DiffusionPinNode): string {

  const [owner, name] = (node.side === "takes" ? node.pin.upstream : node.pin.consumer).split("/");

  const [cOwner, cName] = node.pin.consumer.split("/");

  if (node.pin.bump !== null && node.pin.bump !== undefined) {

    return hubUrl(node.repo.base, cOwner, cName, { kind: "proposal", number: node.pin.bump });

  }

  return hubUrl(node.repo.base, owner, name, { kind: "repository" });

}

/** The repository's Diffusion tab on the hub. */

export function diffusionTab(repo: HubRepo): string {

  return hubUrl(repo.base, repo.owner, repo.name, { kind: "diffusion" });

}

// Diffusion in the editor, without VS Code (oxygenhub-vscode#5): how a pin

// between an upstream and its consumer looks. The hub's pill has two halves,

// the upstream's state and the consumer's; a tree row has one icon, so it

// shows the more urgent of the two and says both in words.

import type { DiffusionHalf, DiffusionPin } from "./hubapi";

/** A codicon and a theme colour id. */

export interface Look {

  icon: string;

  color: string;

}

/** Most urgent first: a failure, then what nothing checked, then waiting. */

const URGENCY = ["red", "amber", "grey", "green", "off"];

/** The tone a row shows: the more urgent half, ignoring a consumer that does not follow. */

export function tone(pin: DiffusionPin): string {

  const tones = [pin.upstream_state.tone, pin.consumer_state.tone].filter((t) => t !== "off");

  return tones.sort((a, b) => rank(a) - rank(b))[0] ?? "off";

}

function rank(t: string): number {

  const i = URGENCY.indexOf(t);

  return i < 0 ? URGENCY.length : i;

}

export function look(t: string): Look {

  switch (t) {

    case "green":

      return { icon: "pass-filled", color: "testing.iconPassed" };

    case "red":

      return { icon: "error", color: "testing.iconFailed" };

    case "amber":

      return { icon: "warning", color: "list.warningForeground" };

    case "grey":

      return { icon: "clock", color: "testing.iconQueued" };

    default:

      return { icon: "circle-outline", color: "disabledForeground" };

  }

}

/** The row's name: the repository on the other end of the pin. */

export function pinLabel(pin: DiffusionPin, side: "takes" | "gives"): string {

  return side === "takes" ? pin.upstream : pin.consumer;

}

/** "untested │ passes · 2 behind · bump #304", as the hub's pill reads. */

export function pinDescription(pin: DiffusionPin): string {

  const parts = [`${pin.upstream_state.word} │ ${pin.consumer_state.word}`];

  if (pin.behind !== null && pin.behind !== undefined && pin.behind > 0) {

    parts.push(`${pin.behind} behind`);

  }

  if (pin.bump !== null && pin.bump !== undefined) {

    parts.push(`bump #${pin.bump}`);

  }

  return parts.join(" · ");

}

const FOLLOW: Record<string, string> = { off: "does not follow", green: "follows when the upstream is green", any: "follows every move" };

/** The tooltip, in Markdown: both halves' sentences, then the pin. */

export function pinTooltip(pin: DiffusionPin): string {

  const half = (who: string, h: DiffusionHalf) => `**${who}: ${h.word}.** ${h.title}`;

  const run = pin.run !== null && pin.run !== undefined ? ` · run #${pin.run}${pin.run_status ? ` ${pin.run_status}` : ""}` : "";

  return [

    half(pin.upstream, pin.upstream_state),

    half(pin.consumer, pin.consumer_state),

    `Pinned at \`${pin.path}\` on \`${pin.bookmark}\`; ${pin.consumer} ${FOLLOW[pin.follow] ?? pin.follow}.${pin.bump !== null && pin.bump !== undefined ? ` Open bump #${pin.bump}${run}.` : ""}`,

  ].join("\n\n");

}

import { test } from "node:test";

import assert from "node:assert/strict";

import { look, pinDescription, pinLabel, pinTooltip, tone } from "../out/diffusionview.mjs";

const half = (tone, word) => ({ tone, word, title: `${word}.` });

const pin = (over = {}) => ({

  upstream: "doomsdayone/rstar-api",

  consumer: "doomsdayone/metalgear",

  path: "rstar-api",

  bookmark: "develop",

  behind: 2,

  follow: "green",

  bump: 304,

  run: 194,

  run_status: "passed",

  upstream_state: half("amber", "untested"),

  consumer_state: half("green", "passes"),

  ...over,

});

test("a row shows the more urgent half", () => {

  assert.equal(tone(pin()), "amber", "untested outranks passes");

  assert.equal(tone(pin({ consumer_state: half("red", "fails") })), "red");

  assert.equal(tone(pin({ upstream_state: half("green", "checked"), consumer_state: half("off", "not following") })), "green", "not following is not urgent");

  assert.equal(tone(pin({ upstream_state: half("off", "x"), consumer_state: half("off", "y") })), "off");

  assert.equal(look("red").icon, "error");

  assert.equal(look("amber").color, "list.warningForeground");

  assert.equal(look("whatever").icon, "circle-outline");

});

test("a row names the other end and reads like the pill", () => {

  assert.equal(pinLabel(pin(), "takes"), "doomsdayone/rstar-api");

  assert.equal(pinLabel(pin(), "gives"), "doomsdayone/metalgear");

  assert.equal(pinDescription(pin()), "untested │ passes · 2 behind · bump #304");

  assert.equal(pinDescription(pin({ behind: 0, bump: null, consumer_state: half("green", "up to date") })), "untested │ up to date");

  assert.equal(pinDescription(pin({ behind: null, bump: null })), "untested │ passes");

  const tip = pinTooltip(pin());

  assert.match(tip, /\*\*doomsdayone\/rstar-api: untested\.\*\*/);

  assert.match(tip, /Pinned at `rstar-api` on `develop`; doomsdayone\/metalgear follows when the upstream is green\. Open bump #304 · run #194 passed\./);

});

## 0.12.0 (2026-10-13)

- **A Diffusion view (#5).** What each repository takes from and diffuses to, each row reading like the hub's pill (`untested │ passes`), how far behind it is and its open bump; picking a row opens the bump. Needs an OxygenHub with `GET /repos/{o}/{n}/diffusion` (oxygenhub#153).

2. Open a repository whose remote is on that hub. The **OxygenHub** activity bar icon shows Proposals, Issues, Releases, Flow and Diffusion for it.

### See what Diffusion is doing

**Diffusion** lists what each repository takes from (the subrepos it pins) and who takes from it, each with the hub's status in words (`untested │ passes`), how far behind it is and its open bump proposal. Pick a row to open the bump.

### 8.3 Diffusion

The **Diffusion** view (oxygenhub docs/diffusion.md) shows, for each repository, what it **takes from** (the subrepos it pins that are on the hub) and what it **diffuses to** (the repositories on the hub that pin it), from `GET /repos/{o}/{n}/diffusion`. Each row names the repository at the other end and reads like the hub's pill: the upstream's half, then the consumer's (`untested │ passes`), how far behind the pin is and the open bump proposal. Its icon shows the more urgent half: failing red, untested amber, waiting grey, else green; a consumer that does not follow does not count. The tooltip gives both halves' sentences, where the pin is and how the consumer follows. Picking a row opens its bump: beside the code when the bump is on this repository (the proposal detail, as the Proposals view opens it), else on the hub; a row without a bump opens the other repository. **Open on OxygenHub** (inline) opens the row's bump or repository, or a repository's Diffusion tab. Bumps are ordinary proposals, so they are also in Proposals, where they are reviewed, checked out and landed.

  "version": "0.12.0",

        },

        {

          "id": "oxygenhub.diffusion",

          "name": "Diffusion"

        "category": "OxygenHub"

      },

      {

        "command": "oxygenhub.openDiffusionPin",

        "title": "Open Bump or Repository",

      },

      {

        "command": "oxygenhub.openDiffusionOnHub",

        "title": "Open on OxygenHub",

        "category": "OxygenHub",

        "icon": "$(link-external)"

          "when": "view == oxygenhub.proposals || view == oxygenhub.issues || view == oxygenhub.releases || view == oxygenhub.diffusion",

          "command": "oxygenhub.openDiffusionOnHub",

          "when": "view == oxygenhub.diffusion && viewItem =~ /^diffusion/",

          "group": "inline"

        },

        {

        {

          "command": "oxygenhub.openDiffusionPin",

          "when": "false"

        },

        {

          "command": "oxygenhub.openDiffusionOnHub",

          "when": "false"

        },

    "pretest": "esbuild src/hub.ts --bundle --platform=node --format=esm --outfile=out/hub.mjs && esbuild src/provider.ts --bundle --platform=node --format=esm --outfile=out/provider.mjs && esbuild src/refs.ts --bundle --platform=node --format=esm --outfile=out/refs.mjs && esbuild src/flowview.ts --bundle --platform=node --format=esm --outfile=out/flowview.mjs && esbuild src/diffusionview.ts --bundle --platform=node --format=esm --outfile=out/diffusionview.mjs",

import { DiffusionPinNode, DiffusionProvider, diffusionTab, pinUrl } from "./diffusion";

let diffusion: DiffusionProvider;

  diffusion = new DiffusionProvider(() => proposals.repos(), auth);

  context.subscriptions.push(

    vscode.window.registerTreeDataProvider("oxygenhub.diffusion", diffusion),

    // A bump on this repository opens beside the code, as any proposal does;

    // the rest open on the hub.

    vscode.commands.registerCommand("oxygenhub.openDiffusionPin", async (node: DiffusionPinNode) => {

      const bump = node.pin.bump;

      if (node.side === "takes" && bump !== null && bump !== undefined) {

        try {

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

          const [p, checks] = await Promise.all([client.proposal(node.repo.owner, node.repo.name, bump), client.proposalChecks(node.repo.owner, node.repo.name, bump).catch(() => [])]);

          showDetail(node.repo, p, checks);

          return;

        } catch (e) {

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

        }

      }

      void vscode.env.openExternal(vscode.Uri.parse(pinUrl(node)));

    }),

    vscode.commands.registerCommand("oxygenhub.openDiffusionOnHub", (node?: DiffusionPinNode | { kind: "repo"; repo: HubRepo }) => {

      if (node) {

        void vscode.env.openExternal(vscode.Uri.parse(node.kind === "pin" ? pinUrl(node) : diffusionTab(node.repo)));

      }

    }),

  );

  diffusion.refresh();

  /** What the repository takes from and diffuses to (oxygenhub#153). */

  diffusion(owner: string, name: string): Promise<api.Diffusion> {

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

  }

    case "diffusion":

      return `${repo}/diffusion`;

export type DiffusionHalf = {

  title: string;

  tone: string;

  word: string;

};

export type DiffusionPin = {

  behind?: number | null;

  bookmark: string;

  bump?: number | null;

  consumer: string;

  consumer_state: DiffusionHalf;

  follow: string;

  path: string;

  run?: number | null;

  run_status?: string | null;

  upstream: string;

  upstream_state: DiffusionHalf;

};

export type Diffusion = {

  diffuses_to: DiffusionPin[];

  takes_from: DiffusionPin[];

};

export type Via = {

  expires_ms?: number | null;

  key: string;

  name: string;

  revoked: boolean;

  scope: string;

};

  via?: Via | null;

};

export type Label = {

  colour: string;

  description: string;

  name: string;

};

export type Landed = {

  by: string;

  via: string;

  when_ms: number;

  labels?: Label[];

  landed?: Landed | null;

  requested_reviewers?: string[];

export type NewMilestone = {

  description?: string;

  due?: string | null;

  title: string;

};

export type MilestoneEdit = {

  description?: string | null;

  due?: string | null;

  state?: string | null;

  title?: string | null;

};

  via?: string;

  title?: string | null;

};

export type ReleaseEdit = {

  notes?: string | null;

  prerelease?: boolean | null;

  title?: string | null;

};

export type ProposalEdit = {

  body?: string | null;

  labels?: string[] | null;

  state?: string | null;

  owner?: string | null;

  placed?: string;

  waiting?: string;