xtralab 0.15.0 → 0.15.2

package/lib/git/notebookDiff.js

@@ -5,17 +5,11 @@ import { MessageLoop } from '@lumino/messaging';
 import { Widget } from '@lumino/widgets';
 import { FileDiff } from '@pierre/diffs/react';
 import { parseDiffFromFile } from '@pierre/diffs';
-import { resolveDiffTheme } from './diffTheme';
-/**
- * The CSS class added to the root of the notebook diff. Selectors that
- * style cell sections, headers, and the per-cell diff blocks hang off this
- * class.
- */
+import { DIFF_SCROLLBAR_CSS, resolveDiffTheme } from './diffTheme';
 const NOTEBOOK_DIFF_CSS_CLASS = 'jp-xtralab-NotebookDiff';
 /**
- * Parse notebook JSON. Returns `null` if the text doesn't parse or doesn't
- * look like a notebook (missing `cells` array). The caller falls back to a
- * raw text diff so a malformed file is still inspectable.
+ * Parse notebook JSON. Returns `null` when the text is not a notebook so
+ * the caller can fall back to a raw text diff.
  */
 function parseNotebook(text) {
     if (text.length === 0) {
@@ -47,12 +41,6 @@ function emptyNotebook() {
         nbformat_minor: 5
     };
 }
-/**
- * nbformat allows multiline string fields (`source`, stream `text`,
- * `text/plain` outputs, …) to be either a single string or an array of
- * strings. Normalize to one string so equality checks and diffs see the
- * same shape regardless of how the writer chose to serialize it.
- */
 function joinMultiline(value) {
     if (value === undefined) {
         return '';
@@ -63,11 +51,9 @@ function cellSource(cell) {
     return joinMultiline(cell.source);
 }
 /**
- * Canonical text representation of a cell's outputs, used both for equality
- * checks and for the per-cell output diff. Stream and `text/plain` data
- * round-trip verbatim; richer mime types (image/png, text/html, …) collapse
- * to a `<mime-type>` placeholder so diffing image bytes doesn't drown the
- * panel in base64 noise.
+ * Canonical text form of a cell's outputs, used for equality checks and
+ * diffs. Rich mime types collapse to a `<mime-type>` placeholder so base64
+ * payloads don't drown the diff.
  */
 function canonicalOutputs(cell) {
     var _a;
@@ -106,10 +92,6 @@ function formatOutput(output) {
         case 'error': {
             const ename = (_d = output.ename) !== null && _d !== void 0 ? _d : 'Error';
             const evalue = (_e = output.evalue) !== null && _e !== void 0 ? _e : '';
-            // Tracebacks contain ANSI escape codes by default. Strip them so the
-            // diff stays readable — coloring information has no analog in a plain
-            // text diff, and the escapes themselves would inflate every traceback
-            // line into a fake change.
             const traceback = ((_f = output.traceback) !== null && _f !== void 0 ? _f : []).map(stripAnsi).join('\n');
             return `[error]\n${ename}: ${evalue}\n${traceback}`;
         }
@@ -117,20 +99,15 @@ function formatOutput(output) {
             return `[${output.output_type}]`;
     }
 }
-// Matching ANSI escape codes inherently requires a control character in
-// the pattern, which is what no-control-regex flags. Disable the rule on
-// this single literal — silently emitting un-stripped escapes would just
-// reintroduce the very noise stripAnsi exists to remove.
+// Matching ANSI escapes requires a control character in the pattern.
 // eslint-disable-next-line no-control-regex
 const ANSI_ESCAPE_RE = /\x1B\[[0-9;]*[A-Za-z]/g;
 function stripAnsi(value) {
     return value.replace(ANSI_ESCAPE_RE, '');
 }
 /**
- * Stable JSON of the cell's `metadata` object. Keys are sorted recursively
- * so a writer that re-orders the metadata object doesn't surface as a diff.
- * An empty metadata object returns the empty string so freshly-added cells
- * that carry the default `{}` don't produce a `+{}` placeholder section.
+ * Stable sorted JSON of the cell's `metadata`; empty metadata returns ''
+ * so cells carrying the default `{}` don't produce a `+{}` diff section.
  */
 function canonicalMetadata(cell) {
     var _a;
@@ -140,11 +117,6 @@ function canonicalMetadata(cell) {
     }
     return stableStringify(md);
 }
-/**
- * Stable JSON of the notebook-level metadata bundle (kernelspec, language
- * info, nbformat). We diff the bundle as a single block so the user sees
- * all environment-level changes in one place.
- */
 function canonicalNotebookMetadata(notebook) {
     return stableStringify({
         metadata: notebook.metadata,
@@ -166,11 +138,8 @@ function sortKeysReplacer(key, value) {
     return value;
 }
 /**
- * Equality check used to classify matched cells as `unchanged` vs
- * `modified`. Compares the three things we actually render — type, source,
- * outputs, metadata — using the same canonical representations the diff
- * itself sees, so an "equal" verdict here implies all per-cell diff blocks
- * would be empty.
+ * Classify matched cells as `unchanged` vs `modified` using the same
+ * canonical forms the diff renders, so "equal" implies empty per-cell diffs.
  */
 function cellsAreEqual(a, b) {
     return (a.cell_type === b.cell_type &&
@@ -179,16 +148,9 @@ function cellsAreEqual(a, b) {
         canonicalMetadata(a) === canonicalMetadata(b));
 }
 /**
- * Align cells between two notebook revisions. Cells that carry a stable id
- * (nbformat ≥ 4.5) match on their id; remaining cells fall back to
- * positional matching against the next un-consumed unidentified old cell so
- * older notebooks still produce a sensible diff.
- *
- * Output ordering: entries follow new-file order, with cells that exist
- * only in the old revision appended at the end as `removed`. We don't try
- * to interleave removals at their original position — for typical notebook
- * edits this is more readable than guessing alignment between unrelated
- * insertions and deletions.
+ * Align cells between two revisions: stable ids (nbformat ≥ 4.5) match by
+ * id, the rest positionally. Entries follow new-file order with old-only
+ * cells appended as `removed`.
  */
 function alignNotebookCells(oldCells, newCells) {
     const oldById = new Map();
@@ -199,8 +161,6 @@ function alignNotebookCells(oldCells, newCells) {
     });
     const consumed = new Set();
     const entries = [];
-    // Cursor used for positional matching of unidentified cells. Only advances
-    // forward so we don't double-match a single old cell.
     let positionalCursor = 0;
     for (let newIndex = 0; newIndex < newCells.length; newIndex++) {
         const newCell = newCells[newIndex];
@@ -251,13 +211,10 @@ function alignNotebookCells(oldCells, newCells) {
     return entries;
 }
 /**
- * Build a complete notebook diff from the textual contents of two
- * revisions. Returns `null` if either side fails to parse as a notebook;
- * the caller is expected to fall back to a raw text diff in that case.
- *
- * An empty string on either side is treated as an empty notebook (no
- * cells, default metadata) so a freshly-added or deleted notebook still
- * produces a sensible cell-by-cell diff.
+ * Build a notebook diff from the text of two revisions. Returns `null` when
+ * either side fails to parse (caller falls back to a raw text diff); an
+ * empty string counts as an empty notebook so added/deleted notebooks still
+ * diff cell by cell.
  */
 export function buildNotebookDiff(options) {
     var _a;
@@ -291,10 +248,8 @@ function detectLanguage(notebook) {
     return undefined;
 }
 /**
- * Pick a filename whose extension drives `@pierre/diffs`'s syntax
- * highlighter. The library never reads the file from disk — `name` only
- * influences token-level rendering, so any plausible extension that maps
- * to the right language is fine.
+ * Pick a filename whose extension drives the `@pierre/diffs` highlighter;
+ * the library never reads the file, only the extension matters.
  */
 function cellFilename(cell, language) {
     if (cell.cell_type === 'markdown') {
@@ -325,37 +280,9 @@ function cellFilename(cell, language) {
     }
 }
 /**
- * Build the FileContents pair the diff library wants. `kind` controls the
- * filename so each per-cell sub-diff (source, metadata) gets the right
- * extension and therefore the right highlighter.
- */
-function pierreFiles(kind, oldText, newText, oldCell, newCell, language) {
-    let name;
-    if (kind === 'metadata') {
-        name = 'cell-metadata.json';
-    }
-    else {
-        // Use the new cell's type/language when available; fall back to the old
-        // side so a deleted cell still gets the right highlighter.
-        const reference = newCell !== null && newCell !== void 0 ? newCell : oldCell;
-        name = reference !== null ? cellFilename(reference, language) : 'cell.txt';
-    }
-    return {
-        oldFile: { name, contents: oldText },
-        newFile: { name, contents: newText }
-    };
-}
-/**
- * Compute the source / metadata sub-diffs for a single cell entry.
- * Returns the empty list for `unchanged` entries so the caller can collapse
- * them; for `added` / `removed` entries the populated side is paired with
- * an empty counterpart so the library treats every line as an addition or
- * deletion respectively.
- *
- * Outputs are deliberately *not* included here — they're rendered through
- * rendermime side-by-side in {@link OutputsSection} so images render as
- * images, HTML as HTML, etc. The canonical text form survives for equality
- * (it drives the `unchanged` classification) but not for display.
+ * Source / metadata sub-diffs for one cell entry; empty for `unchanged`.
+ * Outputs are excluded on purpose — they render through rendermime in
+ * {@link OutputsSection}; their canonical text form only drives equality.
  */
 function buildCellSubDiffs(entry, language) {
     if (entry.kind === 'unchanged') {
@@ -363,6 +290,7 @@ function buildCellSubDiffs(entry, language) {
     }
     const oldCell = entry.kind === 'added' ? null : entry.oldCell;
     const newCell = entry.kind === 'removed' ? null : entry.newCell;
+    const sourceName = cellFilename(entry.kind === 'removed' ? entry.oldCell : entry.newCell, language);
     const oldSource = oldCell !== null ? cellSource(oldCell) : '';
     const newSource = newCell !== null ? cellSource(newCell) : '';
     const oldMd = oldCell !== null ? canonicalMetadata(oldCell) : '';
@@ -376,35 +304,26 @@ function buildCellSubDiffs(entry, language) {
         if (section.oldText === section.newText) {
             continue;
         }
-        const { oldFile, newFile } = pierreFiles(section.kind, section.oldText, section.newText, oldCell, newCell, language);
+        const name = section.kind === 'metadata' ? 'cell-metadata.json' : sourceName;
         subdiffs.push({
             kind: section.kind,
-            metadata: parseDiffFromFile(oldFile, newFile)
+            metadata: parseDiffFromFile(oldCell === null ? null : { name, contents: section.oldText }, newCell === null ? null : { name, contents: section.newText })
         });
     }
     return subdiffs;
 }
-/**
- * Common diff library options shared across every per-cell sub-diff and
- * the notebook-level metadata diff. Split mode matches the file-diff path
- * and gives the user the same left=old / right=new mental model inside
- * each cell — cells stack vertically but each cell internally reads
- * side-by-side, which matches how nbdime renders.
- */
 function diffLibraryOptions(theme, dark) {
     return {
         diffStyle: 'split',
         disableFileHeader: true,
         theme,
-        themeType: dark ? 'dark' : 'light'
+        themeType: dark ? 'dark' : 'light',
+        unsafeCSS: DIFF_SCROLLBAR_CSS
     };
 }
 /**
- * Mount a Lumino {@link Widget} inside a React tree. The widget is the
- * source of truth for its DOM — React just owns the host element and
- * Lumino owns the content the widget paints into it. Detach + dispose
- * happens on unmount or when a new widget arrives, so the parent doesn't
- * need to manage the widget's lifecycle separately.
+ * Mount a Lumino {@link Widget} inside a React tree; detach + dispose
+ * happens on unmount or when a new widget arrives.
  */
 function LuminoWidget(props) {
     const { widget, className } = props;
@@ -418,31 +337,14 @@ function LuminoWidget(props) {
             Widget.attach(widget, host);
         }
         catch (err) {
-            // Lumino refuses to attach a widget whose host isn't connected to
-            // the document, or that's already attached elsewhere. Either way
-            // there's nothing useful to do here — log and bail so the parent
-            // tree still mounts.
+            // Lumino refuses to attach when the host is not in the document or
+            // the widget is attached elsewhere; log and let the tree mount.
             console.warn('xtralab: Widget.attach failed', err);
             return;
         }
         return () => {
-            // Lumino's `Widget.detach` throws "Widget is not attached" when
-            // either the `IsAttached` flag is false *or* the node is no longer
-            // connected to the document. During a parent React unmount the
-            // host element gets removed from the DOM before this cleanup
-            // runs, so `node.isConnected` is already `false` while the
-            // `IsAttached` flag is still set from our earlier `Widget.attach`
-            // call. Calling `Widget.detach` in that state would throw, and —
-            // worse — `widget.dispose()` re-enters the same detach branch
-            // internally (its `else if (this.isAttached)` guard does not
-            // check the DOM connection), so leaving the flag stale produces
-            // the noisy "Widget is not attached" warning out of `dispose`.
-            //
-            // Resolve the race by driving Lumino's detach lifecycle by hand
-            // when the host has already been torn down: send `BeforeDetach`
-            // and `AfterDetach` so the layout cleanup hooks run and the flag
-            // clears, then dispose. When the host is still connected the
-            // ordinary `Widget.detach` path handles both steps for us.
+            // On parent unmount React removes the host first; detach (and dispose,
+            // which re-enters it) throws on a disconnected node, so message by hand.
             if (widget.isAttached) {
                 if (widget.node.isConnected) {
                     try {
@@ -475,14 +377,8 @@ function LuminoWidget(props) {
     return React.createElement("div", { ref: ref, className: className });
 }
 /**
- * Render a sequence of nbformat outputs through JupyterLab's rendermime,
- * exactly the way a live notebook would. Wrapped here so the side-by-side
- * cell layout can drop a fully-rendered output column on either side
- * without re-implementing rich mime rendering.
- *
- * The output area is created `trusted` because the source git ref is on
- * the user's machine (working tree / index / HEAD). A diff viewer that
- * sandboxed its own user's outputs would just be inconvenient.
+ * Render nbformat outputs through rendermime like a live notebook would.
+ * Trusted: the source git ref already lives on the user's machine.
  */
 function OutputsPreview(props) {
     const { outputs, rendermime, className } = props;
@@ -496,11 +392,8 @@ function OutputsPreview(props) {
     return React.createElement(LuminoWidget, { widget: widget, className: className });
 }
 /**
- * Render markdown source through rendermime so the cell preview matches
- * what JupyterLab would render in a live notebook (LaTeX, syntax-highlighted
- * code fences, sanitized HTML, …). Used for both the rendered preview that
- * sits next to a markdown cell's source diff, and for unchanged markdown
- * cells when the user expands them.
+ * Render markdown source through rendermime so the preview matches a live
+ * notebook (LaTeX, code fences, sanitized HTML).
  */
 function MarkdownPreview(props) {
     const { source, rendermime, className } = props;
@@ -517,11 +410,8 @@ function MarkdownPreview(props) {
     return React.createElement(LuminoWidget, { widget: renderer, className: className });
 }
 /**
- * Two-column "old | new" layout used by both {@link OutputsSection} and
- * {@link MarkdownPreviewSection}. The visible side(s) depend on the cell
- * kind: modified shows both, added shows only new, removed shows only old,
- * unchanged collapses to a single full-width pane (since both sides
- * render the same content).
+ * Two-column "old | new" layout; collapses to a single full-width pane
+ * when only one side has content.
  */
 function SideBySidePanes(props) {
     const { label, oldNode, newNode, hasOld, hasNew } = props;
@@ -536,11 +426,8 @@ function SideBySidePanes(props) {
             both || hasNew ? (React.createElement("div", { className: `${NOTEBOOK_DIFF_CSS_CLASS}-sidePane`, "data-side": "new" }, newNode)) : null)));
 }
 /**
- * Rendered outputs section for a cell. Renders old / new outputs through
- * rendermime in two columns; for added or removed cells only the populated
- * side is shown. Returns `null` (so the section is hidden entirely) when
- * neither side has any outputs, or when the same set of outputs appears
- * on both sides and the host doesn't want the duplicate render.
+ * Rendered outputs for a cell, old / new through rendermime; `null` when
+ * neither side has outputs.
  */
 function OutputsSection(props) {
     var _a, _b;
@@ -554,11 +441,6 @@ function OutputsSection(props) {
     if (!hasOld && !hasNew) {
         return null;
     }
-    // For added / removed cells the parent already lives in a single outer
-    // column — rendering the populated side full width within that column
-    // is the right move. SideBySidePanes itself collapses to a single grid
-    // column when only one side has content, so we can use it for both
-    // cases by feeding it only the side(s) we want.
     const showOld = placement !== 'right' && hasOld;
     const showNew = placement !== 'left' && hasNew;
     if (rendermime === null) {
@@ -567,9 +449,7 @@ function OutputsSection(props) {
     return (React.createElement(SideBySidePanes, { label: trans.__('Outputs'), hasOld: showOld, hasNew: showNew, oldNode: React.createElement(OutputsPreview, { outputs: oldOutputs, rendermime: rendermime }), newNode: React.createElement(OutputsPreview, { outputs: newOutputs, rendermime: rendermime }) }));
 }
 /**
- * Rendered markdown preview section. Sits next to (and below) the markdown
- * source diff so the user sees both the source-level changes and how the
- * rendered cell looks. Skipped for non-markdown cells.
+ * Rendered markdown preview beside the source diff; skipped for non-markdown cells.
  */
 function MarkdownPreviewSection(props) {
     const { entry, rendermime, placement, trans } = props;
@@ -587,14 +467,9 @@ function MarkdownPreviewSection(props) {
     return (React.createElement(SideBySidePanes, { label: trans.__('Rendered'), hasOld: showOld, hasNew: showNew, oldNode: React.createElement(MarkdownPreview, { source: oldSource, rendermime: rendermime }), newNode: React.createElement(MarkdownPreview, { source: newSource, rendermime: rendermime }) }));
 }
 /**
- * The notebook-level diff view. Lays out cells in a 2-column grid where
- * the left column tracks the *old* notebook and the right column tracks
- * the *new* one — modified and unchanged cells span both columns (their
- * internal split-mode FileDiff aligns with the outer columns), added
- * cells live in the right column with an empty placeholder on the left,
- * and removed cells live in the left column with an empty placeholder on
- * the right. The diff library's red/green tint within each cell makes
- * the orientation clear without a separate column header.
+ * Notebook-level diff view: a 2-column grid where the left column tracks
+ * the old notebook and the right the new one — modified/unchanged cells
+ * span both, added cells sit right, removed cells sit left.
  */
 export function NotebookDiffView(props) {
     const { diff, dark, pierreTheme, rendermime, trans } = props;
@@ -606,12 +481,8 @@ export function NotebookDiffView(props) {
         diff.notebookMetadataDiff !== null ? (React.createElement(NotebookMetadataBlock, { metadata: diff.notebookMetadataDiff, theme: theme, dark: dark, trans: trans })) : null));
 }
 /**
- * Place a single cell entry into the outer 2-column grid. Modified /
- * unchanged entries span the full row; added entries take the right
- * column with an empty placeholder on the left; removed entries take the
- * left column with an empty placeholder on the right. The placeholders
- * are visible (subtle dashed outline) so the user can see *where* a
- * cell was inserted or removed relative to the other side.
+ * Place one cell entry into the 2-column grid, with a visible placeholder
+ * marking where a cell was inserted or removed on the other side.
  */
 function CellEntryRow(props) {
     const { entry, trans } = props;
@@ -672,16 +543,12 @@ function cellEntryKey(entry) {
 function CellDiffBlock(props) {
     var _a, _b;
     const { entry, language, theme, dark, rendermime, placement, trans } = props;
-    // Unchanged cells start collapsed — the user opted out of seeing those
-    // sections by virtue of them being unchanged. A toggle lets them peek if
-    // they want.
     const [collapsed, setCollapsed] = React.useState(entry.kind === 'unchanged');
     const subdiffs = React.useMemo(() => (collapsed ? [] : buildCellSubDiffs(entry, language)), [collapsed, entry, language]);
     const cellType = referenceCellType(entry);
     const indexLabel = cellIndexLabel(entry);
     const isCodeCell = cellType === 'code';
-    // Output rendering is only meaningful for code cells. Markdown / raw cells
-    // never carry outputs in nbformat.
+    // Only code cells carry outputs in nbformat.
     const showOutputs = isCodeCell && entry.kind !== 'unchanged';
     return (React.createElement("section", { className: `${NOTEBOOK_DIFF_CSS_CLASS}-cell`, "data-kind": entry.kind, "data-cell-type": cellType, "data-placement": placement },
         React.createElement("header", { className: `${NOTEBOOK_DIFF_CSS_CLASS}-cellHeader`, onClick: () => setCollapsed(c => !c), role: "button", tabIndex: 0, "aria-expanded": !collapsed, onKeyDown: event => {
@@ -708,19 +575,14 @@ function CellDiffBlock(props) {
 }
 function CellSubDiff(props) {
     const { kind, metadata, theme, dark, placement, trans } = props;
-    // For modified / unchanged cells the diff spans both outer columns, and
-    // split mode lets it visually align with the outer old | new lanes. For
-    // added / removed cells the diff sits inside a single outer column, so
-    // unified mode keeps the content readable instead of leaving half the
-    // column empty.
+    // Full-width cells align split mode with the outer old|new lanes;
+    // single-column cells read better unified.
     const diffStyle = placement === 'full' ? 'split' : 'unified';
     return (React.createElement("div", { className: `${NOTEBOOK_DIFF_CSS_CLASS}-subdiff`, "data-section": kind },
         React.createElement("div", { className: `${NOTEBOOK_DIFF_CSS_CLASS}-subdiffLabel` }, subdiffLabel(kind, trans)),
         React.createElement(FileDiff, { fileDiff: metadata, 
-            // See diffWidget.tsx — the worker bootstrap can't resolve through
-            // JupyterLab's federation pipeline, so every diff in this extension
-            // runs on the main thread. Cell diffs are small enough that this is
-            // not a performance concern.
+            // The worker bootstrap can't resolve through JupyterLab's federation
+            // pipeline (see diffSurface.tsx); run on the main thread.
             disableWorkerPool: true, options: { ...diffLibraryOptions(theme, dark), diffStyle } })));
 }
 function NotebookMetadataBlock(props) {
@@ -734,12 +596,8 @@ function NotebookMetadataBlock(props) {
             React.createElement(CellSubDiff, { kind: "metadata", metadata: metadata, theme: theme, dark: dark, placement: "full", trans: trans }))));
 }
 /**
- * Body for an unchanged cell when the user has expanded it. The cell's
- * content matches on both sides, so we render once full-width: markdown
- * cells go through rendermime (if available) so they look like the live
- * notebook would render them, code cells fall through to a verbatim
- * pre-formatted block, and any code outputs render through rendermime
- * below the source.
+ * Expanded body of an unchanged cell, rendered once full-width: markdown
+ * through rendermime, code verbatim with outputs below.
  */
 function UnchangedCellBody(props) {
     var _a;

package/lib/git/tokens.d.ts

@@ -1,39 +1,74 @@
 /**
- * Types shared by the git plugin. Mirror the response shapes returned by the
- * `jupyterlab_git` server extension's REST API so the frontend can stay
- * tightly coupled to a single version of those endpoints.
+ * Types shared by the git plugin, mirroring the response shapes of the
+ * `jupyterlab_git` server extension's REST API.
  */
 /**
- * A single entry in the `files` array returned by `POST /git/<path>/status`.
- * `x` and `y` are the porcelain-format index/worktree status codes (see
- * `git status --porcelain`); `to` is the file's current path relative to the
- * git repository root, `from` is the source path for renames (and equal to
- * `to` for any other status).
+ * One entry of the `files` array from `POST /git/<path>/status`. `x`/`y` are
+ * the porcelain index/worktree codes; `to` is the current repo-relative path
+ * and `from` the rename source (equal to `to` for any other status).
  */
 export interface IGitStatusFile {
+    /**
+     * The porcelain status code for the index side.
+     */
     x: string;
+    /**
+     * The porcelain status code for the worktree side.
+     */
     y: string;
+    /**
+     * The current repo-relative path of the file.
+     */
     to: string;
+    /**
+     * The rename source path; equal to `to` for any other status.
+     */
     from: string;
+    /**
+     * Whether the file content is binary; `null` when undetermined.
+     */
     is_binary: boolean | null;
 }
 /**
  * Response shape of `POST /git/<path>/status`.
  */
 export interface IGitStatusResult {
+    /**
+     * The return code of the git command.
+     */
     code: number;
+    /**
+     * The current branch name; `null` when it is not available.
+     */
     branch: string | null;
+    /**
+     * The upstream remote branch; `null` when none is set.
+     */
     remote: string | null;
+    /**
+     * The number of commits ahead of the upstream branch.
+     */
     ahead: number;
+    /**
+     * The number of commits behind the upstream branch.
+     */
     behind: number;
+    /**
+     * The changed files reported by `git status`.
+     */
     files: IGitStatusFile[];
+    /**
+     * The in-progress repository state (merge, rebase, ...), when reported.
+     */
     state?: number;
+    /**
+     * An error message, present when the command fails.
+     */
     message?: string;
 }
 /**
- * Reference accepted by `POST /git/<path>/content` to identify which version
- * of a file to fetch. `WORKING` is the on-disk copy, `INDEX` is the staged
- * copy, and a `git` value is any commit-ish (`HEAD`, a SHA, …).
+ * Reference accepted by `POST /git/<path>/content`: `WORKING` is the on-disk
+ * copy, `INDEX` the staged copy, `git` any commit-ish.
  */
 export type GitReference = {
     special: 'WORKING' | 'INDEX' | 'BASE';
@@ -41,41 +76,48 @@ export type GitReference = {
     git: string;
 };
 /**
- * Response shape of `POST /git/<path>/content`. The server only returns text
- * content here; binary files are reported as binary in the status response,
- * and we surface them in the UI without attempting to render their diff.
+ * Response shape of `POST /git/<path>/content`.
  */
 export interface IGitContentResult {
+    /**
+     * The return code of the git command.
+     */
     code: number;
+    /**
+     * The file content at the requested reference.
+     */
     content: string;
+    /**
+     * An error message, present when the command fails.
+     */
     message?: string;
 }
-/**
- * Where a file's change lives relative to the index.
- *
- *   - `staged`   → present in the index, may differ from HEAD
- *   - `unstaged` → present in the worktree, differs from the index
- *
- * A single file can appear in both groups when the worktree has further
- * changes on top of an already-staged version. The panel models that as two
- * separate entries, one per group.
- */
 type FileChangeGroup = 'staged' | 'unstaged';
-/**
- * The user-facing status of a file change. Drives the single-letter badge
- * (M/A/D/R/U/?) shown next to each entry in the panel.
- */
 export type FileChangeStatus = 'modified' | 'added' | 'deleted' | 'renamed' | 'untracked' | 'unmerged' | 'typechange' | 'unknown';
 /**
- * One row in the changes panel. `path` is the file's path relative to the
- * git repository root. `from` is non-`undefined` only for renames, in which
- * case it carries the original path.
+ * One row in the changes panel. `path` is repo-relative; `from` is set only
+ * for renames and carries the original path.
  */
 export interface IFileChange {
+    /**
+     * The repo-relative path of the file.
+     */
     path: string;
+    /**
+     * The rename source path, set only for renames.
+     */
     from?: string;
+    /**
+     * Whether the change is staged or unstaged.
+     */
     group: FileChangeGroup;
+    /**
+     * The change status derived from the porcelain codes.
+     */
     status: FileChangeStatus;
+    /**
+     * Whether the file content is binary; `null` when undetermined.
+     */
     isBinary: boolean | null;
 }
 export {};

package/lib/git/tokens.js

@@ -1,6 +1,5 @@
 /**
- * Types shared by the git plugin. Mirror the response shapes returned by the
- * `jupyterlab_git` server extension's REST API so the frontend can stay
- * tightly coupled to a single version of those endpoints.
+ * Types shared by the git plugin, mirroring the response shapes of the
+ * `jupyterlab_git` server extension's REST API.
  */
 export {};

package/lib/highlight/index.d.ts

@@ -1,15 +1,9 @@
 import { JupyterFrontEndPlugin } from '@jupyterlab/application';
 /**
- * Contribute `xtralab:highlight-lines` and `xtralab:clear-highlights`.
- *
- * The built-in command surface can open a file (`docmanager:open`) and move
- * the cursor to a line (`fileeditor:go-to-line`), but it cannot persistently
- * highlight a span of lines — `documentsearch:start` only marks text matches
- * and hijacks the find box. This plugin fills that gap with a CodeMirror line
- * decoration, so an agent can point at "lines 31–43 of src/index.ts" while it
- * narrates a walkthrough. `xtralab:highlight-lines` opens the file when needed,
- * scrolls the range into view, and replaces any previous highlight in that
- * editor; `xtralab:clear-highlights` removes every highlight.
+ * Contributes `xtralab:highlight-lines` and `xtralab:clear-highlights`,
+ * filling the persistent span-highlight gap in the core command surface
+ * (`documentsearch:start` only marks text matches and hijacks the find box)
+ * so an agent can point at lines while narrating a walkthrough.
  */
 declare const plugin: JupyterFrontEndPlugin<void>;
 export default plugin;