xtralab 0.15.0 → 0.15.2

package/src/fileBrowser/widget.tsx

@@ -17,6 +17,7 @@ import {
 import { Signal, ISignal } from '@lumino/signaling';
 import { AccordionPanel, PanelLayout, Widget } from '@lumino/widgets';
 
+import type { IFileChange } from '../git/tokens';
 import { FileBrowserComponent } from './fileBrowser';
 import { xtralabFileBrowserIcon } from './icons';
 
@@ -42,10 +43,26 @@ const ACCORDION_CSS_CLASS = 'jp-xtralab-FileBrowser-accordion';
 
 const MOVABLE_SECTION_CLASS = 'jp-movable-section';
 
+/**
+ * The options used to create an {@link XtralabFileBrowser}.
+ */
 interface IXtralabFileBrowserOptions {
+  /**
+   * The contents manager backing the tree.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * The document manager used to open files from the tree.
+   */
   docManager: IDocumentManager;
+  /**
+   * Callback invoked with a file's server path when its row is
+   * double-clicked. No double-click handler is installed when absent.
+   */
   onOpenFile?: (serverPath: string) => void;
+  /**
+   * The application language translator.
+   */
   translator?: ITranslator;
 }
 
@@ -56,82 +73,68 @@ interface IXtralabFileBrowserOptions {
  */
 export interface IXtralabFileBrowser {
   /**
-   * The contents manager backing the tree. Exposed so command handlers can
-   * issue contents operations (rename, delete, copy, …) against the same
-   * drive the tree was loaded from.
+   * The contents manager backing the tree; command handlers issue rename,
+   * delete, copy, … against the same drive.
    */
   readonly contentsManager: Contents.IManager;
 
   /**
-   * The toolbar shown above the tree. Plugin code populates it with command
-   * buttons after the widget is constructed.
+   * The toolbar above the tree, populated by plugin code after construction.
    */
   readonly toolbar: Toolbar;
 
   /**
-   * Canonical paths of the items currently selected in the tree. Folder
-   * paths carry a trailing slash; file paths do not.
+   * Canonical selected paths; folder paths carry a trailing slash.
    */
   readonly selectedPaths: readonly string[];
 
   /**
-   * Emits when the tree's selection changes. Commands that have an
-   * `isVisible` / `isEnabled` predicate should listen so they re-evaluate.
+   * Emits when the tree's selection changes.
    */
   readonly selectionChanged: ISignal<IXtralabFileBrowser, readonly string[]>;
 
   /**
-   * Emits when {@link refresh} is called. The React component listens and
-   * re-fetches the directories that were previously loaded so the tree
-   * matches the contents on disk again.
+   * Git changes from the latest status poll, one per staged or unstaged
+   * change; paths are repo-relative.
+   */
+  readonly gitChanges: readonly IFileChange[];
+
+  /**
+   * Emits when {@link refresh} is called.
    */
   readonly refreshRequested: ISignal<IXtralabFileBrowser, void>;
 
   /**
-   * Emits when the widget is asked to surface a newly-created path
-   * (for example, after the toolbar's "new folder" command). The React
-   * component listens and inserts the path into the model so the user
-   * sees the new item without a full refresh.
+   * Emits a newly-created canonical path so the tree inserts it without a
+   * full refresh.
    */
   readonly pathAdded: ISignal<IXtralabFileBrowser, string>;
 
   /**
-   * Emits when an external caller asks the tree to scroll to and select
-   * the given canonical path. The React component listens, lazily loads
-   * any unloaded ancestor directories, expands them, and selects the
-   * target. Used by the editor breadcrumbs to jump back to a file or
-   * folder shown in the breadcrumb trail.
+   * Emits a canonical path to load, expand, select, and scroll to. Used by
+   * the editor breadcrumbs.
    */
   readonly revealRequested: ISignal<IXtralabFileBrowser, string>;
 
   /**
-   * Emits when an external caller asks the tree to return to the
-   * workspace root: clear any current selection and scroll back to the
-   * first row. Distinct from {@link revealRequested} because the
-   * workspace root has no tree row of its own — it cannot be reached
-   * by passing a path.
+   * Emits when the tree should return to the workspace root — the root has
+   * no tree row of its own, so it cannot be revealed by path.
    */
   readonly rootRequested: ISignal<IXtralabFileBrowser, void>;
 
   /**
-   * Emits when an external caller asks the tree to collapse every
-   * expanded folder. The React component listens and walks the loaded
-   * directories, calling `.collapse()` on each expanded one.
+   * Emits when every expanded folder should collapse.
    */
   readonly collapseAllRequested: ISignal<IXtralabFileBrowser, void>;
 
   /**
-   * Whether the filter box above the tree is shown. Mirrors the default
-   * file browser's `showFileFilter`: hidden on startup and flipped by the
-   * toolbar toggle. Also forced to `true` when the tree opens a search
-   * session on its own — typing a letter while the tree has focus.
+   * Whether the filter box above the tree is shown; also forced `true` when
+   * the tree opens a search session itself (typing while it has focus).
    */
   readonly fileFilterVisible: boolean;
 
   /**
-   * Emits when {@link fileFilterVisible} changes. The React component
-   * listens to show or hide the filter box; the toggle command listens
-   * to refresh its toggled state.
+   * Emits when {@link fileFilterVisible} changes.
    */
   readonly fileFilterVisibleChanged: ISignal<IXtralabFileBrowser, boolean>;
 
@@ -141,24 +144,19 @@ export interface IXtralabFileBrowser {
   refresh(): void;
 
   /**
-   * Notify the React component that a new path was created and should
-   * appear in the tree. `canonicalPath` follows the `@pierre/trees`
-   * convention: directories carry a trailing slash, files do not.
+   * Notify the React component that a new canonical path was created and
+   * should appear in the tree.
    */
   notifyPathAdded(canonicalPath: string): void;
 
   /**
-   * Ask the tree to reveal {@link canonicalPath}: load and expand any
-   * unloaded ancestor directories, then select and scroll the target
-   * into view. `canonicalPath` follows the `@pierre/trees` convention
-   * (directories carry a trailing slash, files do not). Must be a
-   * non-empty path — use {@link scrollToRoot} for the root gesture.
+   * Reveal a non-empty canonical path: load and expand ancestors, then
+   * select and scroll to it. Use {@link scrollToRoot} for the root gesture.
    */
   reveal(canonicalPath: string): void;
 
   /**
-   * Ask the tree to return to the workspace root: clear any current
-   * selection and scroll back to the top of the tree.
+   * Return to the workspace root: clear the selection and scroll to the top.
    */
   scrollToRoot(): void;
 
@@ -177,6 +175,10 @@ export interface IXtralabFileBrowser {
    */
   toggleFileFilter(): void;
 
+  /**
+   * The DOM node of the movable "Files" section, used to locate the panel
+   * currently hosting the tree.
+   */
   readonly sectionNode: HTMLElement;
 }
 
@@ -228,67 +230,123 @@ export class XtralabFileBrowser
     layout.addWidget(this._section);
   }
 
+  /**
+   * The contents manager backing the tree.
+   */
   get contentsManager(): Contents.IManager {
     return this._contentsManager;
   }
 
+  /**
+   * The toolbar above the tree.
+   */
   get toolbar(): Toolbar {
     return this._toolbar;
   }
 
+  /**
+   * Canonical selected paths; folder paths carry a trailing slash.
+   */
   get selectedPaths(): readonly string[] {
     return this._selectedPaths;
   }
 
+  /**
+   * A signal emitted when the tree's selection changes.
+   */
   get selectionChanged(): ISignal<this, readonly string[]> {
     return this._selectionChanged;
   }
 
+  /**
+   * Git changes from the latest status poll.
+   */
+  get gitChanges(): readonly IFileChange[] {
+    return this._gitChanges;
+  }
+
+  /**
+   * A signal emitted when {@link refresh} is called.
+   */
   get refreshRequested(): ISignal<this, void> {
     return this._refreshRequested;
   }
 
+  /**
+   * A signal emitting a newly-created canonical path for the tree to insert.
+   */
   get pathAdded(): ISignal<this, string> {
     return this._pathAdded;
   }
 
+  /**
+   * A signal emitting a canonical path to load, expand, select, and scroll to.
+   */
   get revealRequested(): ISignal<this, string> {
     return this._revealRequested;
   }
 
+  /**
+   * A signal emitted when the tree should return to the workspace root.
+   */
   get rootRequested(): ISignal<this, void> {
     return this._rootRequested;
   }
 
+  /**
+   * A signal emitted when every expanded folder should collapse.
+   */
   get collapseAllRequested(): ISignal<this, void> {
     return this._collapseAllRequested;
   }
 
+  /**
+   * Whether the filter box above the tree is shown.
+   */
   get fileFilterVisible(): boolean {
     return this._fileFilterVisible;
   }
 
+  /**
+   * A signal emitted when {@link fileFilterVisible} changes.
+   */
   get fileFilterVisibleChanged(): ISignal<this, boolean> {
     return this._fileFilterVisibleChanged;
   }
 
   /**
-   * Update the cached selection. Called from the React tree when the
-   * underlying `@pierre/trees` model emits a selection change.
+   * Update the cached selection from the React tree.
    */
   updateSelection(paths: readonly string[]): void {
     this._selectedPaths = paths;
     this._selectionChanged.emit(paths);
   }
 
+  /**
+   * Update the cached git changes from the React tree's status poll.
+   */
+  updateGitChanges(changes: readonly IFileChange[]): void {
+    this._gitChanges = changes;
+  }
+
+  /**
+   * Trigger a refresh of every loaded directory in the tree.
+   */
   refresh(): void {
     this._refreshRequested.emit();
   }
 
+  /**
+   * Notify the tree that a new canonical path was created.
+   */
   notifyPathAdded(canonicalPath: string): void {
     this._pathAdded.emit(canonicalPath);
   }
 
+  /**
+   * Reveal a non-empty canonical path in the tree; use {@link scrollToRoot}
+   * for the workspace root, which has no tree row of its own.
+   */
   reveal(canonicalPath: string): void {
     if (canonicalPath.length === 0) {
       throw new Error(
@@ -298,14 +356,23 @@ export class XtralabFileBrowser
     this._revealRequested.emit(canonicalPath);
   }
 
+  /**
+   * Return to the workspace root: clear the selection and scroll to the top.
+   */
   scrollToRoot(): void {
     this._rootRequested.emit();
   }
 
+  /**
+   * Ask the tree to collapse every currently expanded folder.
+   */
   collapseAll(): void {
     this._collapseAllRequested.emit();
   }
 
+  /**
+   * Show or hide the filter box above the tree.
+   */
   setFileFilterVisible(visible: boolean): void {
     if (this._fileFilterVisible === visible) {
       return;
@@ -314,30 +381,51 @@ export class XtralabFileBrowser
     this._fileFilterVisibleChanged.emit(visible);
   }
 
+  /**
+   * Toggle the filter box above the tree.
+   */
   toggleFileFilter(): void {
     this.setFileFilterVisible(!this._fileFilterVisible);
   }
 
+  /**
+   * The DOM node of the movable "Files" section.
+   */
   get sectionNode(): HTMLElement {
     return this._section.node;
   }
 
+  /**
+   * Whether the panel currently holds no sections, its own tree included.
+   */
   get isEmpty(): boolean {
     return this._panelLayout.widgets.length === 0;
   }
 
+  /**
+   * A signal emitted when a section is added to or removed from the panel.
+   */
   get contentChanged(): ISignal<this, void> {
     return this._contentChanged;
   }
 
+  /**
+   * A signal emitting each section entry announced to the move plugin.
+   */
   get sectionAdded(): ISignal<this, ISectionEntry> {
     return this._sectionAdded;
   }
 
+  /**
+   * The accordion hosting the sections, or `null` while the tree sits alone.
+   */
   get accordionPanel(): AccordionPanel | null {
     return this._accordion;
   }
 
+  /**
+   * Section widgets hosted from other panels; the tree section is excluded.
+   */
   get sections(): ReadonlyArray<Widget> {
     if (!this._accordion) {
       return [];
@@ -361,6 +449,10 @@ export class XtralabFileBrowser
       : [];
   }
 
+  /**
+   * Detach and return the tree section so the move plugin can re-host it;
+   * `null` for any other id or when the section is already away from home.
+   */
   removeSectionById(sectionId: string): Widget | null {
     if (sectionId !== TREE_SECTION_ID || !this._isSectionHome()) {
       return null;
@@ -377,6 +469,9 @@ export class XtralabFileBrowser
     return this._section;
   }
 
+  /**
+   * Re-attach the tree section after a move back to this panel.
+   */
   reinsertSection(widget: Widget): void {
     if (this._accordion) {
       this._accordion.insertWidget(0, widget);
@@ -418,6 +513,10 @@ export class XtralabFileBrowser
     this._contentChanged.emit();
   }
 
+  /**
+   * Remove a hosted section; the accordion is torn down once only the
+   * panel's own tree section (or nothing) remains.
+   */
   removeSectionWidget(widget: Widget): void {
     if (!this._accordion || widget.parent !== this._accordion) {
       return;
@@ -459,6 +558,7 @@ export class XtralabFileBrowser
   private _translator: ITranslator | undefined;
   private _selectedPaths: readonly string[] = [];
   private _selectionChanged = new Signal<this, readonly string[]>(this);
+  private _gitChanges: readonly IFileChange[] = [];
   private _refreshRequested = new Signal<this, void>(this);
   private _pathAdded = new Signal<this, string>(this);
   private _revealRequested = new Signal<this, string>(this);
@@ -475,17 +575,35 @@ export class XtralabFileBrowser
   private _sectionAdded = new Signal<this, ISectionEntry>(this);
 }
 
+/**
+ * The options used to create an {@link XtralabFileTreeContent}.
+ */
 interface IFileTreeContentOptions {
+  /**
+   * The contents manager backing the tree.
+   */
   contentsManager: Contents.IManager;
+  /**
+   * The document manager used to open files from the tree.
+   */
   docManager: IDocumentManager;
+  /**
+   * Callback invoked with a file's server path when its row is
+   * double-clicked. No double-click handler is installed when absent.
+   */
   onOpenFile?: (serverPath: string) => void;
+  /**
+   * The application language translator.
+   */
   translator?: ITranslator;
+  /**
+   * The host widget the React tree reports selection and state changes to.
+   */
   browser: XtralabFileBrowser;
 }
 
 /**
- * The React-rendered region of the file browser. Lives inside the host
- * widget below the toolbar and renders the actual tree.
+ * The React-rendered region below the toolbar that hosts the actual tree.
  */
 class XtralabFileTreeContent extends ReactWidget {
   constructor(options: IFileTreeContentOptions) {
@@ -493,6 +611,9 @@ class XtralabFileTreeContent extends ReactWidget {
     this._options = options;
   }
 
+  /**
+   * Render the file browser React component.
+   */
   protected render(): React.ReactElement {
     return (
       <FileBrowserComponent

package/src/fileTypeIcons/index.ts

@@ -25,13 +25,9 @@ function representativePath(
   if (extension === undefined || extension === '') {
     return null;
   }
-  // Extensions are stored with a leading dot (e.g. `.py`, `.tar.gz`).
   return `file${extension.startsWith('.') ? extension : `.${extension}`}`;
 }
 
-/**
- * Point a file type's icon at the tree glyph for its extension.
- */
 function applyTreeIcon(fileType: DocumentRegistry.IFileType): void {
   const path = representativePath(fileType);
   if (path === null) {
@@ -79,9 +75,6 @@ const EXTRA_FILE_TYPE_EXTENSIONS = [
   '.wasm'
 ];
 
-/**
- * Register icon-only file types for unclaimed source extensions.
- */
 function registerExtraFileTypes(docRegistry: DocumentRegistry): void {
   for (const extension of EXTRA_FILE_TYPE_EXTENSIONS) {
     const icon = getSpecificTreeIcon(`file${extension}`);
@@ -125,7 +118,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
       applyTreeIcon(fileType);
     }
     registerExtraFileTypes(docRegistry);
-    // Pick up file types registered after this plugin activates.
     docRegistry.changed.connect((_, args) => {
       if (
         args.type === 'fileType' &&
@@ -148,8 +140,6 @@ const plugin: JupyterFrontEndPlugin<void> = {
           }
         };
         setIcon();
-        // Keep the tab icon right after a rename, and release the listener
-        // when the document closes.
         widget.context.pathChanged.connect(setIcon);
         widget.disposed.connect(() => {
           widget.context.pathChanged.disconnect(setIcon);

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