Shared utilities

In short: JavaScript's Map and Set compare object keys by identity, so two equal vscode.Uris are different keys. HashMap and HashSet key on toString() instead, and each has a read-only interface that the Commit type uses. commit_topology fills in every commit's ancestor and descendant sets and finds the working copy and its parent. Merge holds a value that may be conflicted, as jj does. dispose disposes everything in an array and empties it. check.ts and time.ts just re-export the commit graph's own copies, which give compile-time exhaustive switch checks and Mercurial-style "5 minutes ago" strings. check and time are the only files nothing imports at this pin.

1. Files and who uses them

The re-exports exist because of Bazel visibility. //src/ui/commit_graph/utils is visible only to //src/utils and to the commit graph's own packages (BUILD.bazel). //src/utils is public and depends on it (BUILD.bazel, target), so it is the route for any other code to reach those helpers.

2. HashMap

A thin wrapper over Map<string, [Key, Value]>. Every operation calls key.toString() and uses the result as the real key. The original key object is stored next to the value so keys() and entries() can hand it back (source). Two keys are "equal" exactly when their strings are.

HashMapKey

hashmap.ts, lines 150–155

Methods

hashmap.ts, lines 42–112

ReadonlyHashMap is the same surface minus set, delete, clear and putIfAbsent (source). HashMap implements it, so a function can take a map it promises not to change, as calculateAncestors does.

The two private iterator classes implement both next() and [Symbol.iterator] over the same inner iterator (source). for … of and spreading go through the generator. Calling next() by hand goes through the method instead.

3. HashSet

A HashMap<Key, void> with set-shaped methods: add, has, delete, clear, size(), keys(), and [Symbol.iterator], so it can be used directly in for … of. The constructor adds each element of an optional iterable (source). It has no values, entries or forEach.

ReadonlyHashSet keeps only [Symbol.iterator], keys, has and size (source). The public Commit type exposes ancestors and descendants through it, and MutableCommit maps each such field back to a writable HashSet so the client can fill them in (api.ts).

4. commit_topology

Functions over a list of Commits (source). Upstream says it was copied from Google's internal code with few changes, and added the ancestors and descendants fields after it. Only the two calculate… functions and getCommitIdToCommitMap are called, from the end of SubprocessClient.getCommits; the other three are used only by their tests or not at all.

Both calculate… functions are an iterative post-order depth-first search, so a long history can't overflow the call stack. For each commit they keep an explicit stack. A commit whose set is already non-empty is finished and is popped. Otherwise every parent that is in the map and not yet finished is pushed, and the commit is revisited later. Once none are pushed, the commit's set becomes itself plus the union of its parents' sets, so each set is computed once and reused, whatever order the map iterates in. A parent ID that isn't in the map, such as a public base outside the revset, is added as-is but not followed. A non-empty set doubles as the "visited" mark, which works because every finished set contains at least the commit itself.

5. check: exhaustiveness helpers

Re-exported unchanged from the commit graph (source). Each helper takes a value whose type should already have been narrowed to never (or to an explicitly allowed type). Adding a new enum or union member then turns every unhandled switch into a compile error.

The file's comments point to an internal "go/guards-and-assertions" library. It was carried over from Google's internal TypeScript tooling and has no public counterpart here.

6. dispose

dispose(disposables) calls dispose() on each element in order, then sets the array's length to 0 so the same array can be reused or disposed again harmlessly (source). If one dispose() throws, the loop stops: the remaining elements aren't disposed and the array isn't emptied.

7. time: relative timestamps

age(unixSeconds) deliberately mirrors Mercurial's age template filter, so the graph reads like hg xl (source). The graph webview shows it through jj-time-ago-text (graph-webview).

1. The exact same second is now.
2. More than 30 years in the future is in the distant future. More than two years in the past is Date.toDateString(), for example Tue Mar 03 2020.
3. Otherwise it picks the largest unit that fits at least twice: years of 365 days, months of 30 days, weeks, days, hours, minutes, seconds (table). So 90 seconds is 90 seconds ago, and 13 days is 13 days ago, not 1 week ago. A future date gets … from now.

8. Tests and build

time.ts has its tests next to the original in src/ui/commit_graph/utils/. dispose, check, getWorkingCopyCommit, getCommitIdToCommitMap and getChangeIdToCommitsMap have none of their own. The topology tests build commits with the fakeCommit fake from //src/testing.

hashmap, hashset, merge and commit_topology are now their own ts_library targets, "to avoid circular dependencies with api.ts": api.ts needs HashSet and Merge, and commit_topology needs //src/api (BUILD.bazel). The utils target globs the rest of *.ts, excluding those four, and the ts_library macro drops the *_test.ts files from it, so they compile only into the tests target (BUILD.bazel).

9. Loose ends at this pin

• Unused exports. The check and time re-exports have no importers, and getWorkingCopyCommit, getOnlyWorkingCopyParentCommit, getChangeIdToCommitsMap and getEvolvedCommit have no callers outside tests.
• toString is not checked. Every object has one, so the type system accepts a key whose toString is the default [object Object]. All such keys would collapse into one entry. vscode.Uri, the only key type used, has a real one.
• ValueIterator.next() at the end. It reads next.value[1] without the ?. that KeyIterator has, so calling next() by hand past the last value throws a TypeError (source). for … of isn't affected.
• Shared tuples. entries() yields the stored [key, value] arrays, so a caller that mutates one changes the map without updating its string key.
• HashSet's iterator comment still calls it "the ImmutableSet" (source).