api.ts 90.3%

102 of 113 lines run, 8 of 8 functions, 30 of 32 branches · run #26 on main · run missed

// The API this extension exports to others (spec §9, "extension API"): the
// same idea as the built-in Git extension's `getAPI()`. A forge extension
// such as oxygenhub-vscode consumes it instead of running oxy itself, and
// registers a remote provider so this extension can offer "Open on …"
// links without knowing any hub.
//
// Pure functions live here so they can be tested with plain Node; the
// vscode-facing object is assembled in extension.ts.

/** What a remote-aware extension registers. */
export interface RemoteProvider {
  /** A stable id, e.g. `oxygenhub`. */
  readonly id: string;
  /** Shown in menus: "Open on OxygenHub". */
  readonly label: string;
  /** Whether this provider understands a remote URL. */
  matches(remoteUrl: string): boolean;
  /** A web URL for a thing in that remote, or undefined when the provider has none. */
  urlFor(remoteUrl: string, target: RemoteTarget): string | undefined;
}

export type RemoteTarget =
  | { kind: "repository" }
  | { kind: "bookmark"; name: string }
  | { kind: "change"; hash: string }
  | { kind: "file"; reference: string; path: string; line?: number; endLine?: number }
  | { kind: "proposals" }
  | { kind: "issues" };

/** A minimal view of one repository, stable across versions. */
export interface RepositoryHandle {
  readonly root: string;
  /** `oxy status --json` as last refreshed, or undefined before the first refresh. */
  readonly status: unknown;
  readonly bookmarks: { name: string; heads: string[]; current?: boolean }[];
  readonly currentBookmark: string | undefined;
  /** The repository's remotes, with the CA file each names for a self-signed hub. */
  remotes(): Promise<{ name: string; url: string; ca?: string }[]>;
  /** Run an oxy command in this repository and parse its JSON output. */
  json<T>(args: string[]): Promise<T>;
  refresh(): Promise<void>;
}

export interface OxygenAPI {
  readonly version: 1;
  readonly repositories: readonly RepositoryHandle[];
  /** Fires with the repository whose status changed. */
  readonly onDidChangeStatus: (listener: (repo: RepositoryHandle) => void) => { dispose(): void };
  /** Fires when repositories are discovered or removed. */
  readonly onDidChangeRepositories: (listener: () => void) => { dispose(): void };
  getRepository(fsPath: string): RepositoryHandle | undefined;
  registerRemoteProvider(provider: RemoteProvider): { dispose(): void };
  /** The providers registered so far, for callers that build their own menus. */
  remoteProviders(): readonly RemoteProvider[];
}

/** The provider (and remote) to use for a repository's remotes, if any. */
export function pickProvider(providers: readonly RemoteProvider[], remotes: { name: string; url: string }[]): { provider: RemoteProvider; remote: { name: string; url: string } } | undefined {
  // Prefer a remote called origin or earth, then any.
  const ordered = [...remotes].sort((a, b) => rank(a.name) - rank(b.name));
  for (const remote of ordered) {
    for (const provider of providers) {
      if (provider.matches(remote.url)) {
        return { provider, remote };
      }
    }
  }
  return undefined;
}

function rank(name: string): number {
  return name === "origin" ? 0 : name === "hub" ? 1 : 2;
}

/** The repository handle a folder path belongs to: the longest root that prefixes it. */
export function repositoryFor(roots: string[], fsPath: string): string | undefined {
  let best: string | undefined;
  for (const r of roots) {
    if ((fsPath === r || fsPath.startsWith(r.endsWith("/") ? r : r + "/")) && (!best || r.length > best.length)) {
      best = r;
    }
  }
  return best;
}

/**
 * A state address for permalinks, as OxygenHub writes it: the state's head
 * hashes, sorted and joined with `+`. Undefined without heads.
 */
export function stateSpec(heads: readonly string[]): string | undefined {
  const hex = [...new Set(heads.map((h) => h.toLowerCase()))].filter((h) => /^[0-9a-f]{64}$/.test(h)).sort();
  return hex.length > 0 && hex.length === new Set(heads).size ? hex.join("+") : undefined;
}

/**
 * The 1-based lines to link: the selection when the clicked line is inside it
 * (or nothing was clicked), otherwise the clicked line alone. `selection` is
 * 1-based and inclusive; a selection ending at column 0 of a line does not
 * include that line.
 */
export function linkedLines(clicked: number | undefined, selection: { start: number; end: number; endColumn: number; empty: boolean }): { line: number; endLine?: number } {
  let end = selection.end;
  if (!selection.empty && selection.endColumn === 0 && end > selection.start) {
    end -= 1;
  }
  if (clicked !== undefined && (selection.empty || clicked < selection.start || clicked > end)) {
    return { line: clicked };
  }
  if (selection.empty || end === selection.start) {
    return { line: selection.start };
  }
  return { line: selection.start, endLine: end };
}

1	0×	// The API this extension exports to others (spec §9, "extension API"): the
2	0×	// same idea as the built-in Git extension's `getAPI()`. A forge extension
3	0×	// such as oxygenhub-vscode consumes it instead of running oxy itself, and
4	0×	// registers a remote provider so this extension can offer "Open on …"
5	0×	// links without knowing any hub.
6	0×	//
7	0×	// Pure functions live here so they can be tested with plain Node; the
8	0×	// vscode-facing object is assembled in extension.ts.
9	1×
10	0×	/** What a remote-aware extension registers. */
11		export interface RemoteProvider {
12		/** A stable id, e.g. `oxygenhub`. */
13		readonly id: string;
14		/** Shown in menus: "Open on OxygenHub". */
15		readonly label: string;
16		/** Whether this provider understands a remote URL. */
17		matches(remoteUrl: string): boolean;
18		/** A web URL for a thing in that remote, or undefined when the provider has none. */
19		urlFor(remoteUrl: string, target: RemoteTarget): string \| undefined;
20		}
21	1×
22		export type RemoteTarget =
23		\| { kind: "repository" }
24		\| { kind: "bookmark"; name: string }
25		\| { kind: "change"; hash: string }
26		\| { kind: "file"; reference: string; path: string; line?: number; endLine?: number }
27		\| { kind: "proposals" }
28		\| { kind: "issues" };
29	1×
30	0×	/** A minimal view of one repository, stable across versions. */
31		export interface RepositoryHandle {
32		readonly root: string;
33		/** `oxy status --json` as last refreshed, or undefined before the first refresh. */
34		readonly status: unknown;
35		readonly bookmarks: { name: string; heads: string[]; current?: boolean }[];
36		readonly currentBookmark: string \| undefined;
37		/** The repository's remotes, with the CA file each names for a self-signed hub. */
38		remotes(): Promise<{ name: string; url: string; ca?: string }[]>;
39		/** Run an oxy command in this repository and parse its JSON output. */
40		json<T>(args: string[]): Promise<T>;
41		refresh(): Promise<void>;
42		}
43	1×
44		export interface OxygenAPI {
45		readonly version: 1;
46		readonly repositories: readonly RepositoryHandle[];
47		/** Fires with the repository whose status changed. */
48		readonly onDidChangeStatus: (listener: (repo: RepositoryHandle) => void) => { dispose(): void };
49		/** Fires when repositories are discovered or removed. */
50		readonly onDidChangeRepositories: (listener: () => void) => { dispose(): void };
51		getRepository(fsPath: string): RepositoryHandle \| undefined;
52		registerRemoteProvider(provider: RemoteProvider): { dispose(): void };
53		/** The providers registered so far, for callers that build their own menus. */
54		remoteProviders(): readonly RemoteProvider[];
55		}
56	1×
57	0×	/** The provider (and remote) to use for a repository's remotes, if any. */
58	1×	export function pickProvider(providers: readonly RemoteProvider[], remotes: { name: string; url: string }[]): { provider: RemoteProvider; remote: { name: string; url: string } } \| undefined {
59	1×	// Prefer a remote called origin or earth, then any.
60	1×	const ordered = [...remotes].sort((a, b) => rank(a.name) - rank(b.name));
61	1×	for (const remote of ordered) {
62	1×	for (const provider of providers) {
63	1×	if (provider.matches(remote.url)) {
64	1×	return { provider, remote };
65	1×	}
66	1×	}
67	1×	}
68	1×	return undefined;
69	2×	}
70	2×
71	2×	function rank(name: string): number {
72	2×	return name === "origin" ? 0 : name === "hub" ? 1 : 2;
73	3×	}
74	3×
75	3×	/** The repository handle a folder path belongs to: the longest root that prefixes it. */
76	3×	export function repositoryFor(roots: string[], fsPath: string): string \| undefined {
77	3×	let best: string \| undefined;
78	3×	for (const r of roots) {
79	9×	if ((fsPath === r \|\| fsPath.startsWith(r.endsWith("/") ? r : r + "/")) && (!best \|\| r.length > best.length)) {
80	3×	best = r;
81	3×	}
82	9×	}
83	3×	return best;
84	3×	}
85	1×
86	1×	/**
87	1×	* A state address for permalinks, as OxygenHub writes it: the state's head
88	1×	* hashes, sorted and joined with `+`. Undefined without heads.
89	1×	*/
90	1×	export function stateSpec(heads: readonly string[]): string \| undefined {
91	5×	const hex = [...new Set(heads.map((h) => h.toLowerCase()))].filter((h) => /^[0-9a-f]{64}$/.test(h)).sort();
92	5×	return hex.length > 0 && hex.length === new Set(heads).size ? hex.join("+") : undefined;
93	7×	}
94	7×
95	7×	/**
96	7×	* The 1-based lines to link: the selection when the clicked line is inside it
97	7×	* (or nothing was clicked), otherwise the clicked line alone. `selection` is
98	7×	* 1-based and inclusive; a selection ending at column 0 of a line does not
99	7×	* include that line.
100	7×	*/
101	7×	export function linkedLines(clicked: number \| undefined, selection: { start: number; end: number; endColumn: number; empty: boolean }): { line: number; endLine?: number } {
102	7×	let end = selection.end;
103	7×	if (!selection.empty && selection.endColumn === 0 && end > selection.start) {
104	1×	end -= 1;
105	1×	}
106	7×	if (clicked !== undefined && (selection.empty \|\| clicked < selection.start \|\| clicked > end)) {
107	2×	return { line: clicked };
108	2×	}
109	7×	if (selection.empty \|\| end === selection.start) {
110	2×	return { line: selection.start };
111	2×	}
112	7×	return { line: selection.start, endLine: end };
113	7×	}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

Coverage / src/api.ts 90.3%

Keyboard