@oceanum/oceanumlab 4.6.0

package/src/__tests__/notebookContext.spec.ts

@@ -0,0 +1,97 @@
+import {
+  formatNotebookCells,
+  IContextCell,
+  MAX_CELL_CHARS,
+  MAX_CELLS_BYTES,
+  MAX_NOTEBOOK_CELLS
+} from '../notebookContext';
+
+const code = (source: string): IContextCell => ({ kind: 'code', source });
+const md = (source: string): IContextCell => ({ kind: 'markdown', source });
+
+describe('formatNotebookCells', () => {
+  it('keeps code verbatim and markdown as comments, in notebook order', () => {
+    // The server wraps every cell in one ```python block, so markdown must
+    // arrive as something that reads as Python there.
+    expect(
+      formatNotebookCells([
+        code('import xarray as xr'),
+        md('## Results\n\nWave height is *high*.'),
+        code('ds.plot()')
+      ])
+    ).toEqual([
+      'import xarray as xr',
+      '# %% [markdown]\n# ## Results\n#\n# Wave height is *high*.',
+      'ds.plot()'
+    ]);
+  });
+
+  it('skips empty and whitespace-only cells of either kind', () => {
+    expect(formatNotebookCells([code('  \n'), md(''), code('x = 1')])).toEqual([
+      'x = 1'
+    ]);
+  });
+
+  it('reads CRLF markdown line by line', () => {
+    expect(formatNotebookCells([md('a\r\nb')])).toEqual([
+      '# %% [markdown]\n# a\n# b'
+    ]);
+  });
+
+  it('drops inline image data from markdown but keeps the reference', () => {
+    const image = `![plot](data:image/png;base64,${'A'.repeat(5000)}=)`;
+    expect(formatNotebookCells([md(`See ${image} above.`)])).toEqual([
+      '# %% [markdown]\n# See ![plot](data:…) above.'
+    ]);
+  });
+
+  it('drops inline images whatever parameters they carry', () => {
+    const charset = `![a](data:image/png;charset=utf-8;base64,${'B'.repeat(300)})`;
+    const svg = `<img src="data:image/svg+xml;utf8,%3Csvg%20${'C'.repeat(300)}%3E">`;
+    expect(formatNotebookCells([md(`${charset} and ${svg}`)])).toEqual([
+      '# %% [markdown]\n# ![a](data:…) and <img src="data:…">'
+    ]);
+  });
+
+  it('leaves out a markdown cell the server would reject, keeping the rest', () => {
+    // One oversized cell fails the WHOLE request server-side.
+    const huge = md('x'.repeat(MAX_CELL_CHARS + 1));
+    expect(formatNotebookCells([code('a = 1'), huge, md('ok')])).toEqual([
+      'a = 1',
+      '# %% [markdown]\n# ok'
+    ]);
+  });
+
+  it('falls back to code only when markdown would exceed the cell limit', () => {
+    const cells = Array.from({ length: MAX_NOTEBOOK_CELLS }, (_, i) =>
+      i % 2 === 0 ? code(`c${i}`) : md(`m${i}`)
+    );
+    cells.push(md('one too many'));
+    const sent = formatNotebookCells(cells);
+    expect(sent).toHaveLength(MAX_NOTEBOOK_CELLS / 2);
+    expect(sent.every(s => !s.startsWith('# %% [markdown]'))).toBe(true);
+  });
+
+  it('falls back to code only when markdown would exceed the byte budget', () => {
+    // The server caps the whole request at 2 MiB, history and run outputs
+    // included. A notebook whose code fits must not be pushed over by prose.
+    const codeCells = Array.from({ length: 10 }, (_, i) =>
+      code(`x${i} = "${'a'.repeat(60000)}"`)
+    );
+    const prose = Array.from({ length: 10 }, () => md('b'.repeat(60000)));
+    const sent = formatNotebookCells([...codeCells, ...prose]);
+    expect(sent).toHaveLength(10);
+    expect(sent.every(s => !s.startsWith('# %% [markdown]'))).toBe(true);
+  });
+
+  it('counts the budget in UTF-8 bytes, not characters', () => {
+    // 'é' is 2 bytes: in characters these cells are just under the budget, in
+    // bytes well over it.
+    const half = Math.floor(MAX_CELLS_BYTES / 2) - 100;
+    const sent = formatNotebookCells([
+      code('é'.repeat(half)),
+      md('b'.repeat(half))
+    ]);
+    expect(sent).toHaveLength(1);
+  });
+});

package/src/__tests__/notebookHost.spec.ts

@@ -0,0 +1,195 @@
+import type { JupyterFrontEnd } from '@jupyterlab/application';
+import type { INotebookTracker } from '@jupyterlab/notebook';
+import { NotebookPanel } from '@jupyterlab/notebook';
+import { notebookHost } from '../notebookHost';
+
+// The real module pulls in ES-module UI code that jest cannot load; only the
+// class, for `instanceof`, is needed here.
+jest.mock('@jupyterlab/notebook', () => ({
+  NotebookPanel: class NotebookPanel {}
+}));
+
+interface IFakeContent {
+  widgets: unknown[];
+  activeCellIndex: number;
+}
+
+/** A notebook panel whose file has not been read yet; `load` reads it. */
+function unloaded(
+  id: string,
+  cells = 3,
+  path = 'work/other.ipynb'
+): { panel: NotebookPanel; content: IFakeContent; load: () => void } {
+  let load: () => void = () => undefined;
+  const ready = new Promise<void>(resolve => {
+    load = resolve;
+  });
+  const content: IFakeContent = {
+    widgets: new Array(cells).fill(null),
+    activeCellIndex: 0
+  };
+  const panel = Object.create(NotebookPanel.prototype) as NotebookPanel;
+  Object.defineProperty(panel, 'id', { value: id });
+  Object.defineProperty(panel, 'context', { value: { ready, path } });
+  Object.defineProperty(panel, 'content', { value: content });
+  return { panel, content, load };
+}
+
+function fakeLab(
+  execute: (command: string, args: unknown) => Promise<unknown>,
+  tracked: NotebookPanel[] = []
+) {
+  const activated: string[] = [];
+  const commands = { execute: jest.fn(execute) };
+  const shell = {
+    currentWidget: null as unknown,
+    activateById: (id: string) => {
+      activated.push(id);
+    }
+  };
+  const tracker = {
+    has: (widget: unknown) => tracked.includes(widget as NotebookPanel),
+    find: (test: (panel: NotebookPanel) => boolean) => tracked.find(test)
+  };
+  return {
+    app: { commands, shell } as unknown as JupyterFrontEnd,
+    tracker: tracker as unknown as INotebookTracker,
+    commands,
+    shell,
+    activated
+  };
+}
+
+const flush = (): Promise<void> =>
+  new Promise(resolve => setTimeout(resolve, 0));
+
+const never = (): Promise<unknown> => new Promise(() => undefined);
+
+describe('notebookHost: re-opening', () => {
+  it('re-opens a notebook only once its file has been read', async () => {
+    // Reading the file replaces every cell, so an answer placed before then
+    // would be wiped when it arrived.
+    const { panel, load } = unloaded('nb');
+    const { app, tracker } = fakeLab(async () => panel);
+    let result: NotebookPanel | null | undefined;
+    void notebookHost(app, tracker)
+      .reopen('work/a.ipynb')
+      .then(p => {
+        result = p;
+      });
+
+    await flush();
+    expect(result).toBeUndefined();
+
+    load();
+    await flush();
+    expect(result).toBe(panel);
+  });
+
+  it('selects the last cell, so that answers go at the end', async () => {
+    // It opens with its first cell selected, and answers go below the
+    // selected cell: above the user's work.
+    const { panel, content, load } = unloaded('nb', 30);
+    const { app, tracker } = fakeLab(async () => panel);
+    load();
+
+    await notebookHost(app, tracker).reopen('work/a.ipynb');
+
+    expect(content.activeCellIndex).toBe(29);
+  });
+
+  it('uses a notebook the user has open already, leaving its selection as it is', async () => {
+    // They closed the pinned tab and opened the same file again themselves.
+    const { panel, content, load } = unloaded('theirs', 30, 'work/a.ipynb');
+    content.activeCellIndex = 7;
+    const { app, tracker, commands } = fakeLab(async () => null, [panel]);
+    load();
+
+    await expect(
+      notebookHost(app, tracker).reopen('work/a.ipynb')
+    ).resolves.toBe(panel);
+    expect(content.activeCellIndex).toBe(7);
+    expect(commands.execute).not.toHaveBeenCalled();
+  });
+
+  it('gives up on a notebook that never loads, rather than stalling the chat', async () => {
+    const { panel } = unloaded('nb');
+    const { app, tracker } = fakeLab(async () => panel);
+
+    await expect(
+      notebookHost(app, tracker, 10).reopen('work/a.ipynb')
+    ).resolves.toBeNull();
+  });
+
+  it('gives up on an open that never finishes, rather than stalling the chat', async () => {
+    const { app, tracker } = fakeLab(never);
+
+    await expect(
+      notebookHost(app, tracker, 10).reopen('work/a.ipynb')
+    ).resolves.toBeNull();
+  });
+
+  it('reports a notebook that cannot be re-opened as none', async () => {
+    const { app, tracker } = fakeLab(async () => {
+      throw new Error('not found');
+    });
+
+    await expect(
+      notebookHost(app, tracker).reopen('work/gone.ipynb')
+    ).resolves.toBeNull();
+  });
+});
+
+describe('notebookHost: creating', () => {
+  it('creates a notebook, and brings it to the front once it has loaded', async () => {
+    const { panel, load } = unloaded('new');
+    const { app, tracker, commands, activated } = fakeLab(async () => panel);
+    let result: NotebookPanel | null | undefined;
+    void notebookHost(app, tracker)
+      .create()
+      .then(p => {
+        result = p;
+      });
+
+    await flush();
+    expect(commands.execute).toHaveBeenCalledWith('notebook:create-new', {
+      kernelName: 'python3'
+    });
+    expect(result).toBeUndefined();
+    expect(activated).toEqual([]);
+
+    load();
+    await flush();
+    expect(result).toBe(panel);
+    expect(activated).toEqual(['new']);
+  });
+
+  it('takes no notebook but the one it created', async () => {
+    // Anything else could be a notebook the user opened meanwhile.
+    const { app, tracker, activated } = fakeLab(async () => undefined);
+
+    await expect(notebookHost(app, tracker).create()).resolves.toBeNull();
+    expect(activated).toEqual([]);
+  });
+
+  it('gives up on a notebook that is never created', async () => {
+    const { app, tracker, activated } = fakeLab(never);
+
+    await expect(notebookHost(app, tracker, 10).create()).resolves.toBeNull();
+    expect(activated).toEqual([]);
+  });
+});
+
+describe('notebookHost: the active tab', () => {
+  it('is the notebook in it, or none when the tab is not a notebook', () => {
+    const { panel } = unloaded('nb');
+    const { app, tracker, shell } = fakeLab(async () => null, [panel]);
+    const host = notebookHost(app, tracker);
+
+    shell.currentWidget = panel;
+    expect(host.activeTab()).toBe(panel);
+
+    shell.currentWidget = { id: 'terminal-1' };
+    expect(host.activeTab()).toBeNull();
+  });
+});

package/src/__tests__/notebookRun.spec.ts

@@ -0,0 +1,95 @@
+import { harvestOutputs, stripAnsi, MAX_OBSERVED_CHARS } from '../notebookRun';
+import type * as nbformat from '@jupyterlab/nbformat';
+
+const stream = (name: 'stdout' | 'stderr', text: string | string[]) =>
+  ({ output_type: 'stream', name, text }) as nbformat.IStream;
+
+const error = (ename: string, evalue: string, traceback: string[]) =>
+  ({ output_type: 'error', ename, evalue, traceback }) as nbformat.IError;
+
+describe('harvestOutputs', () => {
+  it('concatenates stdout streams in order and reports ok', () => {
+    const out = harvestOutputs([
+      stream('stdout', 'rows 240\n'),
+      stream('stdout', ['max ', '2.5\n'])
+    ]);
+    expect(out).toEqual({
+      status: 'ok',
+      stdout: 'rows 240\nmax 2.5\n',
+      error: null
+    });
+  });
+
+  it('turns an error output into an error run with the traceback', () => {
+    const out = harvestOutputs([
+      stream('stdout', 'before\n'),
+      error('NameError', "name 'ds' is not defined", [
+        '\u001b[0;31mNameError\u001b[0m Traceback',
+        "name 'ds' is not defined"
+      ])
+    ]);
+    expect(out.status).toBe('error');
+    expect(out.stdout).toBe('before\n');
+    expect(out.error).toContain("NameError: name 'ds' is not defined");
+    // ANSI colour codes are for a terminal, not for the model.
+    expect(out.error).not.toContain('\u001b[');
+    expect(out.error).toContain('NameError Traceback');
+  });
+
+  it('folds stderr into the error text when the run failed', () => {
+    const out = harvestOutputs([
+      stream('stderr', 'FutureWarning: something\n'),
+      error('ValueError', 'bad', [])
+    ]);
+    expect(out.status).toBe('error');
+    expect(out.error).toContain('ValueError: bad');
+    expect(out.error).toContain('FutureWarning');
+  });
+
+  it('does not send rendered outputs like DataFrame reprs', () => {
+    const out = harvestOutputs([
+      {
+        output_type: 'execute_result',
+        data: { 'text/plain': 'huge dataframe repr' },
+        metadata: {},
+        execution_count: 1
+      } as nbformat.IExecuteResult
+    ]);
+    expect(out).toEqual({ status: 'ok', stdout: '', error: null });
+  });
+
+  it('is ok with no outputs at all', () => {
+    expect(harvestOutputs([])).toEqual({
+      status: 'ok',
+      stdout: '',
+      error: null
+    });
+  });
+
+  it('keeps only the tail of a huge stdout; the server reads no more', () => {
+    const lines = Array.from({ length: 5000 }, (_, i) => `line ${i}\n`);
+    const out = harvestOutputs([stream('stdout', lines)]);
+    expect(out.stdout.length).toBeLessThan(MAX_OBSERVED_CHARS + 100);
+    expect(out.stdout).toMatch(/^…\[\d+ chars truncated\]\n/);
+    expect(out.stdout).toMatch(/line 4999\n$/);
+  });
+});
+
+describe('stripAnsi', () => {
+  it('removes colour and cursor codes', () => {
+    expect(stripAnsi('\u001b[1;31mred\u001b[0m plain')).toBe('red plain');
+  });
+
+  it('removes private-mode and OSC sequences from progress bars', () => {
+    expect(stripAnsi('\u001b[?25l50%\u001b[?25h')).toBe('50%');
+    expect(stripAnsi('\u001b]0;title\u0007done')).toBe('done');
+  });
+
+  it('does not swallow text between an ST-terminated and a BEL-terminated OSC', () => {
+    expect(
+      stripAnsi(
+        '\u001b]8;;http://x\u001b\\link\u001b]8;;\u001b\\ then \u001b]0;t\u0007end'
+      )
+    ).toBe('link then end');
+  });
+});

package/src/__tests__/notebookSnapshot.spec.ts

@@ -0,0 +1,62 @@
+import type { Notebook } from '@jupyterlab/notebook';
+import { snapshotFromIpynb, snapshotOf } from '../notebookContext';
+
+const cell = (type: string, source: string) => ({
+  model: { type, sharedModel: { getSource: () => source } }
+});
+
+describe('snapshotOf: an open notebook', () => {
+  it('reads its code and markdown cells in order, and its selected cell', () => {
+    const selected = cell('code', 'df.head()');
+    const notebook = {
+      widgets: [
+        cell('code', 'x = 1'),
+        cell('raw', 'not context'),
+        cell('markdown', '## Notes'),
+        selected
+      ],
+      activeCell: selected
+    } as unknown as Notebook;
+
+    expect(snapshotOf(notebook)).toEqual({
+      cells: [
+        { kind: 'code', source: 'x = 1' },
+        { kind: 'markdown', source: '## Notes' },
+        { kind: 'code', source: 'df.head()' }
+      ],
+      selected: { source: 'df.head()', isCode: true }
+    });
+  });
+});
+
+describe('snapshotFromIpynb: a closed notebook, read from its file', () => {
+  it('reads code and markdown cells in order, from either form of source', () => {
+    // nbformat allows a cell's source as one string or as a list of lines.
+    const snapshot = snapshotFromIpynb({
+      cells: [
+        { cell_type: 'code', source: ['x = 1\n', 'y = 2'] },
+        { cell_type: 'raw', source: 'not context' },
+        { cell_type: 'markdown', source: '## Notes' }
+      ]
+    });
+
+    expect(snapshot).toEqual({
+      cells: [
+        { kind: 'code', source: 'x = 1\ny = 2' },
+        { kind: 'markdown', source: '## Notes' }
+      ],
+      selected: null
+    });
+  });
+
+  it('reads anything unexpected as no cells rather than failing', () => {
+    // Context is best-effort: a file that is not quite a notebook must not
+    // cost the user the answer.
+    for (const content of [null, 'text', {}, { cells: 'no' }]) {
+      expect(snapshotFromIpynb(content)).toEqual({ cells: [], selected: null });
+    }
+    expect(
+      snapshotFromIpynb({ cells: [null, { cell_type: 'code' }] }).cells
+    ).toEqual([{ kind: 'code', source: '' }]);
+  });
+});

package/src/__tests__/oceanumlab.spec.ts

@@ -0,0 +1,9 @@
+/**
+ * Example of [Jest](https://jestjs.io/docs/getting-started) unit tests
+ */
+
+describe('@oceanum/oceanumlab', () => {
+  it('should be tested', () => {
+    expect(1 + 1).toEqual(2);
+  });
+});