#N and @user completion, and hovers on #N (0.4.0) f902d5b8bfeb

// `#N` and `@user` completion, and hover on `#N` (spec §6.2), in the

// Oxygen commit box and in review comments. The numbers are the

// repository's issues and proposals (one number space, as on the hub);

// the users are the people who opened or are assigned to them.

import * as vscode from "vscode";

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

import { HubAuth } from "./auth";

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

import { numberAt, rootFromScmQuery, typingAt } from "./refs";

interface Ref {

  number: number;

  kind: "issue" | "proposal";

  title: string;

  state: string;

  author: string;

}

interface Index {

  at: number;

  refs: Map<number, Ref>;

  users: Set<string>;

}

/** How long an index is reused before the hub is asked again. */

const FRESH_MS = 60_000;

/** Where references are typed: the SCM commit box and comment editors. */

export const SELECTOR: vscode.DocumentSelector = [{ scheme: "vscode-scm" }, { scheme: "comment" }];

export class ReferenceIndex {

  private readonly cache = new Map<string, Index>();

  constructor(

    private readonly auth: HubAuth,

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

  ) {}

  clear(): void {

    this.cache.clear();

  }

  /** The repository a document types into: the SCM box's root, else the only hub repository. */

  async repoFor(doc: vscode.TextDocument): Promise<HubRepo | undefined> {

    const repos = await this.repos();

    const root = doc.uri.scheme === "vscode-scm" ? rootFromScmQuery(doc.uri.query) : undefined;

    if (root) {

      return repos.find((r) => r.handle.root === root);

    }

    return repos.length === 1 ? repos[0] : undefined;

  }

  async indexOf(repo: HubRepo): Promise<Index> {

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

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

    if (hit && Date.now() - hit.at < FRESH_MS) {

      return hit;

    }

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

    const [issues, proposals] = await Promise.all([client.issues(repo.owner, repo.name, "all").catch(() => [] as api.Issue[]), client.proposals(repo.owner, repo.name).catch(() => [] as api.Proposal[])]);

    const refs = new Map<number, Ref>();

    const users = new Set<string>();

    for (const i of issues) {

      refs.set(i.number, { number: i.number, kind: "issue", title: i.title, state: i.state, author: i.author });

      users.add(i.author);

      i.assignees.forEach((a) => users.add(a));

    }

    for (const p of proposals) {

      refs.set(p.number, { number: p.number, kind: "proposal", title: p.title, state: p.state, author: p.author });

      users.add(p.author);

    }

    const me = this.auth.sessionFor(repo.base)?.username;

    if (me) {

      users.add(me);

    }

    users.delete("");

    const index = { at: Date.now(), refs, users };

    this.cache.set(key, index);

    return index;

  }

}

export class ReferenceCompletions implements vscode.CompletionItemProvider {

  constructor(private readonly index: ReferenceIndex) {}

  async provideCompletionItems(doc: vscode.TextDocument, pos: vscode.Position): Promise<vscode.CompletionItem[]> {

    const before = doc.lineAt(pos.line).text.slice(0, pos.character);

    const typing = typingAt(before);

    const repo = typing && (await this.index.repoFor(doc));

    if (!typing || !repo) {

      return [];

    }

    const idx = await this.index.indexOf(repo);

    const range = new vscode.Range(pos.line, typing.start, pos.line, pos.character);

    if (typing.kind === "number") {

      // Open items first, then newest.

      const refs = [...idx.refs.values()].sort((a, b) => Number(a.state !== "open") - Number(b.state !== "open") || b.number - a.number);

      return refs.map((r, i) => {

        const item = new vscode.CompletionItem({ label: `#${r.number}`, description: r.title }, r.kind === "issue" ? vscode.CompletionItemKind.Issue : vscode.CompletionItemKind.Reference);

        item.detail = `${r.kind} · ${r.state} · ${r.author}`;

        item.filterText = `#${r.number} ${r.title}`;

        item.sortText = String(i).padStart(6, "0");

        item.insertText = `#${r.number}`;

        item.range = range;

        return item;

      });

    }

    return [...idx.users].sort().map((u) => {

      const item = new vscode.CompletionItem(`@${u}`, vscode.CompletionItemKind.User);

      item.insertText = `@${u}`;

      item.range = range;

      return item;

    });

  }

}

export class ReferenceHovers implements vscode.HoverProvider {

  constructor(private readonly index: ReferenceIndex) {}

  async provideHover(doc: vscode.TextDocument, pos: vscode.Position): Promise<vscode.Hover | undefined> {

    const at = numberAt(doc.lineAt(pos.line).text, pos.character);

    const repo = at && (await this.index.repoFor(doc));

    if (!at || !repo) {

      return undefined;

    }

    const r = (await this.index.indexOf(repo)).refs.get(at.number);

    if (!r) {

      return undefined;

    }

    const url = `${repo.base}/${repo.owner}/${repo.name}/${r.kind}/${r.number}`;

    const md = new vscode.MarkdownString(`**${r.kind === "issue" ? "Issue" : "Proposal"} #${r.number}** · ${r.state}\n\n${r.title}\n\n_${r.author}_ · [open on the hub](${url})`);

    return new vscode.Hover(md, new vscode.Range(pos.line, at.start, pos.line, at.end));

  }

}

// `#N` and `@user` in text the user is typing (spec §6.2): what is being

// completed at the cursor, and which reference a position sits on. No

// vscode imports, so it is tested with plain Node.

/** A reference being typed: `#12` (issue or proposal) or `@an` (a user). */

export type Typing = { kind: "number"; prefix: string; start: number } | { kind: "user"; prefix: string; start: number };

/**

 * What the text before the cursor is in the middle of typing, if anything.

 * A reference starts a word: after the line start, whitespace or an

 * opening bracket, so `a#1` and `mail@host` are not references.

 */

export function typingAt(before: string): Typing | undefined {

  const n = /(^|[\s([{])#(\d*)$/.exec(before);

  if (n) {

    return { kind: "number", prefix: n[2], start: before.length - n[2].length - 1 };

  }

  const u = /(^|[\s([{])@([A-Za-z0-9][A-Za-z0-9_-]*|)$/.exec(before);

  if (u) {

    return { kind: "user", prefix: u[2], start: before.length - u[2].length - 1 };

  }

  return undefined;

}

/** The `#N` reference covering `column` of `line`, with its span. */

export function numberAt(line: string, column: number): { number: number; start: number; end: number } | undefined {

  const re = /(^|[\s([{])#(\d+)\b/g;

  for (let m = re.exec(line); m; m = re.exec(line)) {

    const start = m.index + m[1].length;

    const end = start + 1 + m[2].length;

    if (column >= start && column <= end) {

      return { number: Number(m[2]), start, end };

    }

  }

  return undefined;

}

/** A repository root named by an SCM input box's URI query (`rootUri=file:///…`). */

export function rootFromScmQuery(query: string): string | undefined {

  const raw = new URLSearchParams(query).get("rootUri");

  if (!raw) {

    return undefined;

  }

  try {

    return decodeURIComponent(new URL(raw).pathname);

  } catch {

    return undefined;

  }

}

// Parsing #N and @user as they are typed and hovered.

import { test } from "node:test";

import assert from "node:assert/strict";

import { typingAt, numberAt, rootFromScmQuery } from "../out/refs.mjs";

test("what is being typed", () => {

  assert.deepEqual(typingAt("Fixes #"), { kind: "number", prefix: "", start: 6 });

  assert.deepEqual(typingAt("Fixes #1"), { kind: "number", prefix: "1", start: 6 });

  assert.deepEqual(typingAt("#12"), { kind: "number", prefix: "12", start: 0 });

  assert.deepEqual(typingAt("(see #4"), { kind: "number", prefix: "4", start: 5 });

  assert.deepEqual(typingAt("cc @an"), { kind: "user", prefix: "an", start: 3 });

  assert.deepEqual(typingAt("@"), { kind: "user", prefix: "", start: 0 });

  assert.equal(typingAt("a#1"), undefined, "not at a word start");

  assert.equal(typingAt("mail@host"), undefined, "an address is not a mention");

  assert.equal(typingAt("#1 done"), undefined, "the cursor has moved on");

});

test("which reference a position sits on", () => {

  const line = "Fixes #12 and (#7), not a#3";

  assert.deepEqual(numberAt(line, 7), { number: 12, start: 6, end: 9 });

  assert.deepEqual(numberAt(line, 9), { number: 12, start: 6, end: 9 });

  assert.deepEqual(numberAt(line, 16), { number: 7, start: 15, end: 17 });

  assert.equal(numberAt(line, 2), undefined);

  assert.equal(numberAt(line, 26), undefined, "a#3 is not a reference");

});

test("the SCM box names its repository", () => {

  assert.equal(rootFromScmQuery("rootUri=" + encodeURIComponent("file:///home/andy/development/oxygen")), "/home/andy/development/oxygen");

  assert.equal(rootFromScmQuery("rootUri=" + encodeURIComponent("file:///home/a%20b/x")), "/home/a b/x");

  assert.equal(rootFromScmQuery(""), undefined);

});

## 0.4.0

- Type `#` in the Oxygen commit box or a review comment to pick an issue or proposal by number or title, and `@` to mention someone who has opened or been assigned one.

- Hover a `#N` to see what it is: kind, state, title and author, with a link to the hub.

- **References while typing**: `#` and `@` completion in the commit box and comments, and a hover on `#N`.

### 6.2 References while typing

In the Oxygen commit box and in comment editors, `#` completes the repository's issues and proposals (one number space, open ones first, newest first; the title is shown and matched) and `@` completes people: the authors and assignees of those issues and proposals, and the signed-in user. Hovering a `#N` shows its kind, state, title and author with a link to the hub. The commit box's repository is the one its source control names (`rootUri`); a comment editor uses the workspace's hub repository when there is exactly one. The lists are fetched per repository and reused for a minute, and cleared on refresh.

  "version": "0.4.0",

    "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",

import { ReferenceCompletions, ReferenceHovers, ReferenceIndex, SELECTOR } from "./references";

let references: ReferenceIndex;

  references = new ReferenceIndex(auth, () => proposals.repos());

  context.subscriptions.push(

    vscode.languages.registerCompletionItemProvider(SELECTOR, new ReferenceCompletions(references), "#", "@"),

    vscode.languages.registerHoverProvider(SELECTOR, new ReferenceHovers(references)),

  );

  references.clear();