xtralab 0.1.0

package/lib/git/index.js

@@ -0,0 +1,74 @@
+import { ILayoutRestorer } from '@jupyterlab/application';
+import { Dialog, ICommandPalette, IThemeManager, WidgetTracker, showDialog, showErrorMessage } from '@jupyterlab/apputils';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { CommandIDs, registerGitCommands } from './commands';
+import { diffWidgetId } from './diffWidget';
+import { GitPanel } from './panel';
+const GIT_PLUGIN_ID = 'xtralab:git';
+const GIT_DIFF_TRACKER_NAMESPACE = 'xtralab-git-diff';
+/**
+ * The git plugin. Adds a VS Code-style "Source Control" panel to the
+ * JupyterLab left sidebar and opens file diffs in the main area when the
+ * user clicks an entry in the panel. Backed by the `jupyterlab_git` server
+ * extension's REST API; the bundled `@jupyterlab/git` frontend is disabled
+ * via `package.json`'s `jupyterlab.disabledExtensions` so the two panels do
+ * not coexist.
+ */
+const plugin = {
+    id: GIT_PLUGIN_ID,
+    description: 'A VS Code-style git changes panel and diff viewer powered by jupyterlab-git and @pierre/diffs.',
+    autoStart: true,
+    optional: [
+        ILayoutRestorer,
+        IThemeManager,
+        ICommandPalette,
+        IRenderMimeRegistry
+    ],
+    activate: (app, restorer, themeManager, commandPalette, rendermime) => {
+        // Match the panel's repo path: empty string means "use the JupyterLab
+        // server's root and let git resolve the enclosing repo".
+        const repoPath = '';
+        // Track open diff widgets so the layout restorer can recreate them on
+        // reload, and so the openDiff handler can reveal an already-open diff
+        // for the same file instead of creating a duplicate.
+        const tracker = new WidgetTracker({
+            namespace: GIT_DIFF_TRACKER_NAMESPACE
+        });
+        const findDiff = (change) => {
+            var _a;
+            const id = diffWidgetId(change);
+            return (_a = tracker.find(widget => widget.id === id)) !== null && _a !== void 0 ? _a : undefined;
+        };
+        const panel = new GitPanel({
+            openDiff: change => {
+                const args = { repoPath, change };
+                void app.commands.execute(CommandIDs.openDiff, args);
+            },
+            confirm: async (title, body, accept) => {
+                const result = await showDialog({
+                    title,
+                    body,
+                    buttons: [Dialog.cancelButton(), Dialog.warnButton({ label: accept })]
+                });
+                return result.button.accept === true;
+            },
+            showError: showErrorMessage
+        });
+        app.shell.add(panel, 'left', { rank: 800 });
+        if (restorer !== null) {
+            restorer.add(panel, panel.id);
+        }
+        registerGitCommands({
+            app,
+            panel,
+            themeManager,
+            commandPalette,
+            contentsManager: app.serviceManager.contents,
+            rendermime,
+            onChanged: () => panel.refresh(),
+            trackDiff: widget => tracker.add(widget),
+            findDiff
+        });
+    }
+};
+export default plugin;

package/lib/git/notebookDiff.d.ts

@@ -0,0 +1,176 @@
+import * as React from 'react';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { type FileDiffMetadata } from '@pierre/diffs';
+/**
+ * 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.
+ */
+export declare const NOTEBOOK_DIFF_CSS_CLASS = "jp-xtralab-NotebookDiff";
+/**
+ * Minimal slice of nbformat 4.x that the diff inspects. Fields we don't
+ * read (attachments, e.g.) are intentionally not narrowed — we still pass
+ * them around as part of the cell, but we never project them into the diff.
+ */
+export interface INotebookCell {
+    cell_type: string;
+    id?: string;
+    source: string | string[];
+    outputs?: INotebookOutput[];
+    metadata?: Record<string, unknown>;
+    execution_count?: number | null;
+    attachments?: Record<string, unknown>;
+}
+export interface INotebookOutput {
+    output_type: string;
+    data?: Record<string, unknown>;
+    text?: string | string[];
+    name?: string;
+    ename?: string;
+    evalue?: string;
+    traceback?: string[];
+    execution_count?: number | null;
+    metadata?: Record<string, unknown>;
+}
+export interface INotebook {
+    cells: INotebookCell[];
+    metadata: Record<string, unknown>;
+    nbformat: number;
+    nbformat_minor: number;
+}
+/**
+ * One entry in the per-cell diff. `unchanged` cells are rendered as a
+ * collapsed summary; the other variants render their source / outputs /
+ * metadata via {@link FileDiff}. The `modified` and `unchanged` branches
+ * carry the same payload but live on separate union members so `Extract`
+ * narrowing works on `kind` literals downstream.
+ */
+export type NotebookCellDiff = {
+    kind: 'modified';
+    oldCell: INotebookCell;
+    newCell: INotebookCell;
+    newIndex: number;
+    oldIndex: number;
+} | {
+    kind: 'unchanged';
+    oldCell: INotebookCell;
+    newCell: INotebookCell;
+    newIndex: number;
+    oldIndex: number;
+} | {
+    kind: 'added';
+    newCell: INotebookCell;
+    newIndex: number;
+} | {
+    kind: 'removed';
+    oldCell: INotebookCell;
+    oldIndex: number;
+};
+/**
+ * Notebook-level diff result returned by {@link buildNotebookDiff}. Returns
+ * `null` from the builder when either side fails to parse — the caller then
+ * falls back to a raw JSON file diff.
+ */
+export interface INotebookDiffResult {
+    oldNotebook: INotebook;
+    newNotebook: INotebook;
+    cells: NotebookCellDiff[];
+    /**
+     * Kernel language pulled from `metadata.language_info.name`, used to pick
+     * a syntax-highlighting filename for code cells.
+     */
+    language: string | undefined;
+    /**
+     * Pre-computed diff for notebook-level metadata (kernelspec, language_info,
+     * nbformat) when it differs between revisions; `null` otherwise so the
+     * section can be hidden without further checks.
+     */
+    notebookMetadataDiff: FileDiffMetadata | null;
+}
+/**
+ * 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.
+ */
+export declare function parseNotebook(text: string): INotebook | null;
+/**
+ * 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 serialise it.
+ */
+export declare function joinMultiline(value: string | string[] | undefined): string;
+export declare function cellSource(cell: INotebookCell): string;
+/**
+ * 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.
+ */
+export declare function canonicalOutputs(cell: INotebookCell): string;
+/**
+ * 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.
+ */
+export declare function canonicalMetadata(cell: INotebookCell): string;
+/**
+ * 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.
+ */
+export declare function canonicalNotebookMetadata(notebook: INotebook): string;
+/**
+ * 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.
+ */
+export declare function cellsAreEqual(a: INotebookCell, b: INotebookCell): boolean;
+/**
+ * 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.
+ */
+export declare function alignNotebookCells(oldCells: INotebookCell[], newCells: INotebookCell[]): NotebookCellDiff[];
+export interface IBuildNotebookDiffOptions {
+    oldText: string;
+    newText: string;
+}
+/**
+ * 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.
+ */
+export declare function buildNotebookDiff(options: IBuildNotebookDiffOptions): INotebookDiffResult | null;
+interface INotebookDiffViewProps {
+    diff: INotebookDiffResult;
+    dark: boolean;
+    rendermime: IRenderMimeRegistry | null;
+}
+/**
+ * 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.
+ */
+export declare function NotebookDiffView(props: INotebookDiffViewProps): React.ReactElement;
+export {};