Skip to content

Commit 292e06b

Browse files
committed
docs(web): docstring coverage for PR diff path collision helpers
1 parent fa8c556 commit 292e06b

1 file changed

Lines changed: 19 additions & 0 deletions

File tree

‎apps/web/src/components/diffs/diffFileTree.logic.ts‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,11 @@ const DIFF_FILE_TREE_FILE_MARK = "\u200b";
5151

5252
const identityPath = (path: string) => path;
5353

54+
/**
55+
* Paths safe for Pierre, and the maps between those paths and the diff.
56+
* `selectionPath` turns a tree row back into the file a click should open.
57+
* `modelPath` turns a diff path into the row stored in the tree.
58+
*/
5459
export interface DiffFileTreeModel {
5560
/** Paths safe to pass to Pierre. Same array as the input when nothing collides. */
5661
readonly paths: ReadonlyArray<string>;
@@ -60,6 +65,11 @@ export interface DiffFileTreeModel {
6065
readonly modelPath: (path: string) => string;
6166
}
6267

68+
/**
69+
* File paths that are also a directory prefix of another path in this diff.
70+
* `office` collides with `office/config.ts`; a shared string prefix such as
71+
* `office` and `officer.ts` does not. Null when every path can be stored as itself.
72+
*/
6373
function collidingFilePaths(paths: ReadonlyArray<string>): ReadonlySet<string> | null {
6474
if (paths.length < 2) return null;
6575
const unique = [...new Set(paths)].toSorted();
@@ -79,6 +89,10 @@ function collidingFilePaths(paths: ReadonlyArray<string>): ReadonlySet<string> |
7989
return colliding.size === 0 ? null : colliding;
8090
}
8191

92+
/**
93+
* A tree path for a file that collides with a directory. Appends the zero-width file
94+
* mark until the path is neither occupied nor a directory prefix of an occupied path.
95+
*/
8296
function modelPathForCollidingFile(path: string, occupied: Set<string>): string {
8397
let modelPath = path;
8498
const collides = (candidate: string) => {
@@ -95,6 +109,11 @@ function modelPathForCollidingFile(path: string, occupied: Set<string>): string
95109
return modelPath;
96110
}
97111

112+
/**
113+
* Rewrites file paths that collide with a directory prefix so both can live in one tree,
114+
* and maps a click on the rewritten row back to the original diff path. Paths that do not
115+
* collide are returned unchanged.
116+
*/
98117
export function diffFileTreeModel(paths: ReadonlyArray<string>): DiffFileTreeModel {
99118
const colliding = collidingFilePaths(paths);
100119
if (colliding === null) {

0 commit comments

Comments
 (0)