xtralab 0.14.1 → 0.15.1

package/src/git/api.ts

@@ -9,29 +9,15 @@ import {
   IGitStatusResult
 } from './tokens';
 
-/**
- * Root URL segment used by the `jupyterlab_git` server extension. Every
- * endpoint hangs off this prefix; the `<repoPath>` between it and the
- * endpoint suffix is the JupyterLab server-relative path of the git
- * repository (URL-encoded). For an empty `repoPath` the URL collapses to
- * `/git/<endpoint>` — a shape git's URL routing also accepts.
- */
 const GIT_NAMESPACE = 'git';
 
-/**
- * Issue a `POST` against a `jupyterlab_git` endpoint that takes a `<path>`
- * prefix (e.g. `/git/<path>/status`). The response body is decoded as JSON;
- * non-2xx responses are surfaced via the JupyterLab `ServerConnection`
- * machinery so callers can show their `message` field as-is.
- */
 async function postWithPath<T>(
   endpoint: string,
   repoPath: string,
   body: unknown
 ): Promise<T> {
   const settings = ServerConnection.makeSettings();
-  // `URLExt.encodeParts` encodes each path segment but preserves slashes
-  // between them — the server expects the path to look like a posix path.
+  // encodeParts keeps the slashes the server's posix-path routing expects.
   const encodedPath = repoPath.length > 0 ? URLExt.encodeParts(repoPath) : '';
   const url = URLExt.join(
     settings.baseUrl,
@@ -50,7 +36,7 @@ async function postWithPath<T>(
     try {
       data = JSON.parse(text) as T;
     } catch {
-      // Fall through into the error handling below.
+      // Non-JSON bodies still surface via the ResponseError below.
     }
   }
   if (!response.ok) {
@@ -62,18 +48,16 @@ async function postWithPath<T>(
 }
 
 /**
- * Fetch `git status --porcelain` for the repository the server resolves at
- * `repoPath`. When `repoPath` is the empty string, git resolves the repo
- * from the JupyterLab server's root directory.
+ * Fetch `git status --porcelain` for the repo at `repoPath` (empty string
+ * resolves from the server's root directory).
  */
 export async function status(repoPath: string): Promise<IGitStatusResult> {
   return postWithPath<IGitStatusResult>('status', repoPath, {});
 }
 
 /**
- * Fetch a file's contents at a particular git reference. `filename` is the
- * file's path relative to the git repository root (matching the `to` field
- * of {@link status}'s response).
+ * Fetch a file's contents at a git reference; `filename` is relative to the
+ * git repository root.
  */
 export async function content(
   repoPath: string,
@@ -88,13 +72,7 @@ export async function content(
 
 /**
  * Expand the porcelain `files` array into one entry per logical change.
- * A single porcelain row may map to two `IFileChange` rows (a file that's
- * both staged and modified again in the worktree); callers that just want
- * a flat list of all changes — without any staged-vs-unstaged grouping —
- * can use this helper.
- *
- * Provided as a manual concat rather than `Array.prototype.flatMap` so we
- * don't pin our `tsconfig.lib` to ES2019.
+ * Manual concat rather than `flatMap` so `tsconfig.lib` need not be ES2019.
  */
 export function expandStatusFiles(files: IGitStatusFile[]): IFileChange[] {
   const result: IFileChange[] = [];
@@ -107,16 +85,12 @@ export function expandStatusFiles(files: IGitStatusFile[]): IFileChange[] {
 }
 
 /**
- * Translate one entry in the porcelain `files` array into the panel's
- * preferred shape. A single porcelain entry may represent up to two changes
- * (one in the index, one in the worktree); we emit one {@link IFileChange}
- * per non-empty side, so a "modified-staged-and-then-modified-again" file
- * shows up twice in the panel — once under "Staged Changes" and once under
- * "Changes" — matching the layout the user sees in VS Code.
+ * Map one porcelain entry to up to two {@link IFileChange} rows — one per
+ * non-empty index/worktree side — so a staged-then-modified-again file
+ * appears under both groups, as in VS Code.
  */
 function porcelainToFileChanges(file: IGitStatusFile): IFileChange[] {
   const result: IFileChange[] = [];
-  // Untracked files are reported with `??` and only appear under "Changes".
   if (file.x === '?' && file.y === '?') {
     return [
       {

package/src/git/askRequest.ts

@@ -9,10 +9,8 @@ import type { IXtralabDiffModel } from './diffWidget';
 type DiffSide = 'deletions' | 'additions';
 
 /**
- * Agent-facing name of a diff content source: the special refs get plain
- * words, a git ref string is used verbatim, anything else falls back to the
- * side name. English on purpose — this ends up in the agent prompt, not in
- * the UI.
+ * Agent-facing name of a diff content source. English on purpose — this
+ * ends up in the agent prompt, not in the UI.
  */
 function describeSource(source: unknown, fallback: string): string {
   if (source === Git.Diff.SpecialRef.WORKING) {
@@ -34,9 +32,6 @@ function sideName(side: DiffSide): string {
   return side === 'deletions' ? 'old side' : 'new side';
 }
 
-/**
- * Extract lines `startLine`–`endLine` (1-indexed, inclusive) from `text`.
- */
 function sliceLines(text: string, startLine: number, endLine: number): string {
   return text
     .split('\n')
@@ -46,14 +41,10 @@ function sliceLines(text: string, startLine: number, endLine: number): string {
 
 /**
  * Build the ask-agent request for a line range selected in a git diff.
- *
- * The range's `side` decides which file version the line numbers (and the
- * embedded snippet) refer to: `deletions` reads from the reference text,
- * anything else — including the sideless context rows of a unified diff,
- * whose gutter shows new-side numbers — reads from the challenger text. A
- * gutter drag that crosses the two split columns has endpoints in different
- * line-number spaces, so it is described textually instead of as a numeric
- * range.
+ * `deletions` ranges index the reference text; other ranges — including
+ * sideless unified context rows, whose gutter shows new-side numbers —
+ * index the challenger. A drag across the two split columns mixes
+ * line-number spaces, so it is described textually instead of numerically.
  */
 export function buildDiffAskRequest(options: {
   model: IXtralabDiffModel;
@@ -97,15 +88,10 @@ export function buildDiffAskRequest(options: {
       ...base,
       startLine,
       endLine,
-      // Only new-side lines of a working-tree diff index the file on disk;
-      // old-side and historical line numbers must not be used to highlight
-      // the working file.
       linesInWorkingFile:
         !isOld && model.challenger.source === Git.Diff.SpecialRef.WORKING,
       text: sliceLines(isOld ? oldText : newText, startLine, endLine),
       location: `the ${sideName(startSide)} (${ref}) of the current git diff`,
-      // New-side lines read as the file's current content, so only old-side
-      // ranges need a clarifying tag in the popup header.
       ...(isOld ? { note: trans.__('old version') } : {})
     },
     anchor

package/src/git/commands.ts

@@ -28,16 +28,25 @@ export namespace CommandIDs {
  * Argument shapes used by {@link CommandIDs.openDiff}.
  */
 export namespace CommandArguments {
+  /**
+   * The arguments for the open-diff command.
+   */
   export interface IOpenDiff {
+    /**
+     * The server-relative path of the repository containing the change.
+     */
     repoPath: string;
+    /**
+     * The file change to show.
+     */
     change: IFileChange;
+    /**
+     * Whether to open the diff as a pinned tab instead of the shared preview.
+     */
     pin?: boolean;
   }
 }
 
-/**
- * Widget id of the single, reused preview diff tab.
- */
 export const PREVIEW_DIFF_WIDGET_ID = 'xtralab:diff:preview';
 
 /**
@@ -70,14 +79,23 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     this._trans = trans;
   }
 
+  /**
+   * The file change currently displayed.
+   */
   get change(): IFileChange {
     return this._change;
   }
 
+  /**
+   * Whether the widget is pinned rather than the shared preview.
+   */
   get pinned(): boolean {
     return this._pinned;
   }
 
+  /**
+   * Pin the widget; a no-op when already pinned.
+   */
   pin(): void {
     if (this._pinned) {
       return;
@@ -86,10 +104,16 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
     this._pinnedChanged.emit(true);
   }
 
+  /**
+   * A signal emitted when the widget becomes pinned.
+   */
   get pinnedChanged(): ISignal<this, boolean> {
     return this._pinnedChanged;
   }
 
+  /**
+   * Display a new file change and update the tab title, caption, and icon.
+   */
   setChange(repoPath: string, change: IFileChange): void {
     this._change = change;
     this.content.setModel(fileChangeToDiffModel(repoPath, change));
@@ -104,21 +128,48 @@ export class DiffMainAreaWidget extends MainAreaWidget<XtralabDiffWidget> {
   private _pinnedChanged = new Signal<this, boolean>(this);
 }
 
+/**
+ * The options used to create a diff main area widget.
+ */
 interface ICreateDiffWidgetOptions {
+  /**
+   * The server-relative path of the repository containing the change.
+   */
   repoPath: string;
+  /**
+   * The file change to display.
+   */
   change: IFileChange;
+  /**
+   * Theme manager the diff view follows; may be `null`.
+   */
   themeManager: IThemeManager | null;
+  /**
+   * Contents manager used to write hunk-discard results.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * Rendermime registry used by notebook diffs; may be `null`.
+   */
   rendermime: IRenderMimeRegistry | null;
+  /**
+   * Ask-agent popup for prompting an agent about diff lines; may be `null`.
+   */
   askAgent: IAskAgent | null;
+  /**
+   * Translation bundle for user-facing strings.
+   */
   trans: TranslationBundle;
+  /**
+   * Whether the widget opens pinned instead of as the shared preview.
+   */
   pinned?: boolean;
+  /**
+   * Callback invoked when the widget becomes pinned.
+   */
   onPinned?: (widget: DiffMainAreaWidget) => void;
 }
 
-/**
- * Build the launcher's diff tab around the shared diff widget.
- */
 function createDiffWidget(
   options: ICreateDiffWidgetOptions
 ): DiffMainAreaWidget {
@@ -158,7 +209,6 @@ function createDiffWidget(
   widget.toolbar.addItem('pin', pinButton);
   addDiffToolbarItems(widget.toolbar, content);
 
-  // Keep chrome visible only while there is a relevant toolbar control.
   const syncToolbarVisibility = (): void => {
     if (widget.isDisposed) {
       return;
@@ -186,7 +236,6 @@ function createDiffWidget(
     }
     syncToolbarVisibility();
   };
-  // Auto-close once a discard leaves nothing to show.
   const onEmptied = (): void => {
     if (!widget.isDisposed) {
       widget.close();
@@ -206,8 +255,17 @@ function createDiffWidget(
   return widget;
 }
 
+/**
+ * The options for {@link registerGitCommands}.
+ */
 interface IRegisterGitCommandsOptions {
+  /**
+   * The JupyterLab application, providing the commands registry and shell.
+   */
   app: JupyterFrontEnd;
+  /**
+   * Theme manager the diff views follow; may be `null`.
+   */
   themeManager: IThemeManager | null;
   /**
    * Contents manager used to write hunk-discard results.
@@ -233,12 +291,14 @@ interface IRegisterGitCommandsOptions {
    * Look up an already-open diff widget for a file change.
    */
   findDiff(change: IFileChange, pin?: boolean): DiffMainAreaWidget | undefined;
+  /**
+   * Callback invoked when a preview diff widget becomes pinned.
+   */
   onPinned(widget: DiffMainAreaWidget): void;
 }
 
 /**
- * Register the launcher's git diff command on the application command
- * registry.
+ * Register the launcher's git diff command.
  */
 export function registerGitCommands(
   options: IRegisterGitCommandsOptions

package/src/git/diffModel.ts

@@ -80,14 +80,39 @@ class FileChangeDiffModel implements IXtralabDiffModel {
     };
   }
 
+  /**
+   * A signal emitted when the reference or challenger changes; this static
+   * model never emits it.
+   */
   readonly changed: ISignal<Git.Diff.IModel, Git.Diff.IModelChange> =
     new Signal<Git.Diff.IModel, Git.Diff.IModelChange>(this);
+  /**
+   * The reference (old) side of the diff.
+   */
   reference: Git.Diff.IContent;
+  /**
+   * The challenger (new) side of the diff.
+   */
   challenger: Git.Diff.IContent;
+  /**
+   * Repo-relative path of the changed file.
+   */
   readonly filename: string;
+  /**
+   * The rename source path; `undefined` for non-renames.
+   */
   readonly oldFilename: string | undefined;
+  /**
+   * Path of the git repository, relative to the server root.
+   */
   readonly repositoryPath: string;
+  /**
+   * Whether the file content is binary.
+   */
   readonly isBinary: boolean;
+  /**
+   * Whether hunks can be discarded through a working-tree save.
+   */
   readonly canDiscard: boolean;
 }