🤖 Store execution outputs in Outputs (#1903)

* feat:add outputs node

* chore: add changeset

* fix: drop style change

* fix: only label first code and outputs

* fix: handle IDs

* fix: return type

* fix: selectAll → select

* refactor: move user expression lowering into function

* refactor: nest declaration

* fix: rename outputs

* refactor: simplify conditions

We don't need to delete nodes without children: they
will simply vanish when lifted

* test: fix tests

* fix: outputs for JATS

* fix: use outputs- for all prefixes

* fix: outputs for JATS

* fix: early exit non-matplotlib

* test: partially fix JATS test

* fix: final JATS test

* test: fix myst-execute tests

* test: fix test titles

* test: fix missing children

* test: more fixes

* test: fix test titles

* fix: handle visibility properly

* fix: update test cases

* 🪪 adding id to outputs enables in-browser compute for figures and embeds

* feat: bump version

* feat: add warning for unbounded migration

* test: bump version in test

* test: bump version

* fix: align isCodeBlock with old PR after rebase

* 🎋post rebase build

* bump date on migrate step

---------

Co-authored-by: Steve Purves <[email protected]>
Co-authored-by: Franklin Koch <[email protected]>

Author: 3 people

.changeset/ten-bats-warn.md

@@ -0,0 +1,10 @@
+---
+"mystmd": minor
+"myst-directives": patch
+"myst-transforms": patch
+"myst-spec-ext": patch
+"myst-execute": patch
+"myst-cli": patch
+---
+
+Add support for new Outputs node

packages/myst-cli/src/process/notebook.ts

@@ -84,6 +84,21 @@ export async function processNotebook(
   return mdast;
 }
 
+/**
+ * Embed the Jupyter output data for a user expression into the AST
+ */
+function embedInlineExpressions(
+  userExpressions: IUserExpressionMetadata[] | undefined,
+  block: GenericNode,
+) {
+  const inlineNodes = selectAll('inlineExpression', block) as InlineExpression[];
+  inlineNodes.forEach((inlineExpression) => {
+    const data = findExpression(userExpressions, inlineExpression.value);
+    if (!data) return;
+    inlineExpression.result = data.result as unknown as Record<string, unknown>;
+  });
+}
+
 export async function processNotebookFull(
   session: ISession,
   file: string,
@@ -136,17 +151,7 @@ export async function processNotebookFull(
           return acc.concat(...cellMdast.children);
         }
         const block = blockParent(cell, cellMdast.children) as GenericNode;
-
-        // Embed expression results into expression
-        const userExpressions = block.data?.[metadataSection] as
-          | IUserExpressionMetadata[]
-          | undefined;
-        const inlineNodes = selectAll('inlineExpression', block) as InlineExpression[];
-        inlineNodes.forEach((inlineExpression) => {
-          const data = findExpression(userExpressions, inlineExpression.value);
-          if (!data) return;
-          inlineExpression.result = data.result as unknown as Record<string, unknown>;
-        });
+        embedInlineExpressions(block.data?.[metadataSection], block);
         return acc.concat(block);
       }
       if (cell.cell_type === CELL_TYPES.raw) {
@@ -165,17 +170,16 @@ export async function processNotebookFull(
           value: ensureString(cell.source),
         };
 
-        // Embed outputs in an output block
-        const output: { type: 'output'; id: string; data: IOutput[] } = {
-          type: 'output',
+        const outputs = {
+          type: 'outputs',
           id: nanoid(),
-          data: [],
+          children: (cell.outputs as IOutput[]).map((output) => ({
+            type: 'output',
+            jupyter_data: output,
+            children: [],
+          })),
         };
-
-        if (cell.outputs && (cell.outputs as IOutput[]).length > 0) {
-          output.data = cell.outputs as IOutput[];
-        }
-        return acc.concat(blockParent(cell, [code, output]));
+        return acc.concat(blockParent(cell, [code, outputs]));
       }
       return acc;
     },

packages/myst-cli/src/spec-version.ts

@@ -1 +1 @@
-export const SPEC_VERSION = 2;
+export const SPEC_VERSION = 3;

packages/myst-cli/src/transforms/code.spec.ts

@@ -162,7 +162,10 @@ function build_mdast(tags: string[], has_output: boolean) {
     ],
   };
   if (has_output) {
-    mdast.children[0].children.push({ type: 'output' });
+    mdast.children[0].children.push({
+      type: 'outputs',
+      children: [{ type: 'output', children: [] }],
+    });
   }
   return mdast;
 }
@@ -261,7 +264,7 @@ describe('propagateBlockDataToCode', () => {
           const mdast = build_mdast([tag], has_output);
           propagateBlockDataToCode(new Session(), new VFile(), mdast);
           let result = '';
-          const outputNode = mdast.children[0].children[1];
+          const outputsNode = mdast.children[0].children[1];
           switch (target) {
             case 'cell':
               result = mdast.children[0].visibility;
@@ -270,12 +273,14 @@ describe('propagateBlockDataToCode', () => {
               result = mdast.children[0].children[0].visibility;
               break;
             case 'output':
-              if (!has_output && target == 'output') {
-                expect(outputNode).toEqual(undefined);
+              if (!has_output) {
+                expect(outputsNode).toEqual(undefined);
                 continue;
               }
-              result = outputNode.visibility;
+              result = outputsNode.visibility;
               break;
+            default:
+              throw new Error();
           }
           expect(result).toEqual(action);
         }
@@ -290,18 +295,18 @@ describe('propagateBlockDataToCode', () => {
         propagateBlockDataToCode(new Session(), new VFile(), mdast);
         const blockNode = mdast.children[0];
         const codeNode = mdast.children[0].children[0];
-        const outputNode = mdast.children[0].children[1];
+        const outputsNode = mdast.children[0].children[1];
         expect(blockNode.visibility).toEqual(action);
         expect(codeNode.visibility).toEqual(action);
         if (has_output) {
-          expect(outputNode.visibility).toEqual(action);
+          expect(outputsNode.visibility).toEqual(action);
         } else {
-          expect(outputNode).toEqual(undefined);
+          expect(outputsNode).toEqual(undefined);
         }
       }
     }
   });
-  it('placeholder creates image node child of output', async () => {
+  it('placeholder creates image node child of outputs', async () => {
     const mdast: any = {
       type: 'root',
       children: [
@@ -313,7 +318,8 @@ describe('propagateBlockDataToCode', () => {
               executable: true,
             },
             {
-              type: 'output',
+              type: 'outputs',
+              children: [],
             },
           ],
           data: {
@@ -323,12 +329,12 @@ describe('propagateBlockDataToCode', () => {
       ],
     };
     propagateBlockDataToCode(new Session(), new VFile(), mdast);
-    const outputNode = mdast.children[0].children[1];
-    expect(outputNode.children?.length).toEqual(1);
-    expect(outputNode.children[0].type).toEqual('image');
-    expect(outputNode.children[0].placeholder).toBeTruthy();
+    const outputsNode = mdast.children[0].children[1];
+    expect(outputsNode.children?.length).toEqual(1);
+    expect(outputsNode.children[0].type).toEqual('image');
+    expect(outputsNode.children[0].placeholder).toBeTruthy();
   });
-  it('placeholder passes with no output', async () => {
+  it('placeholder passes with no outputs', async () => {
     const mdast: any = {
       type: 'root',
       children: [

packages/myst-cli/src/transforms/code.ts

@@ -1,6 +1,6 @@
 import type { GenericNode, GenericParent } from 'myst-common';
 import { NotebookCellTags, RuleId, fileError, fileWarn } from 'myst-common';
-import type { Image, Output } from 'myst-spec-ext';
+import type { Image, Outputs } from 'myst-spec-ext';
 import { select, selectAll } from 'unist-util-select';
 import yaml from 'js-yaml';
 import type { VFile } from 'vfile';
@@ -156,10 +156,9 @@ export function propagateBlockDataToCode(session: ISession, vfile: VFile, mdast:
   const blocks = selectAll('block', mdast) as GenericNode[];
   blocks.forEach((block) => {
     if (!block.data) return;
-    const outputNode = select('output', block) as Output | null;
-    if (block.data.placeholder && outputNode) {
-      if (!outputNode.children) outputNode.children = [];
-      outputNode.children.push({
+    const outputsNode = select('outputs', block) as Outputs | null;
+    if (block.data.placeholder && outputsNode) {
+      outputsNode.children.push({
         type: 'image',
         placeholder: true,
         url: block.data.placeholder as string,
@@ -195,21 +194,21 @@ export function propagateBlockDataToCode(session: ISession, vfile: VFile, mdast:
           if (codeNode) codeNode.visibility = 'remove';
           break;
         case NotebookCellTags.hideOutput:
-          if (outputNode) outputNode.visibility = 'hide';
+          if (outputsNode) outputsNode.visibility = 'hide';
           break;
         case NotebookCellTags.removeOutput:
-          if (outputNode) outputNode.visibility = 'remove';
+          if (outputsNode) outputsNode.visibility = 'remove';
           break;
         case NotebookCellTags.scrollOutput:
-          if (outputNode) outputNode.scroll = true;
+          if (outputsNode) outputsNode.scroll = true;
           break;
         default:
           session.log.debug(`tag '${tag}' is not valid in code-cell tags'`);
       }
     });
     if (!block.visibility) block.visibility = 'show';
     if (codeNode && !codeNode.visibility) codeNode.visibility = 'show';
-    if (outputNode && !outputNode.visibility) outputNode.visibility = 'show';
+    if (outputsNode && !outputsNode.visibility) outputsNode.visibility = 'show';
   });
 }
 
@@ -236,7 +235,7 @@ export function transformLiftCodeBlocksInJupytext(mdast: GenericParent) {
         child.type === 'block' &&
         child.children?.length === 2 &&
         child.children?.[0].type === 'code' &&
-        child.children?.[1].type === 'output'
+        child.children?.[1].type === 'outputs'
       ) {
         newBlocks.push(child as GenericParent);
         newBlocks.push({ type: 'block', children: [] });

packages/myst-cli/src/transforms/outputs.spec.ts

@@ -20,17 +20,40 @@ describe('reduceOutputs', () => {
               ],
             },
             {
-              type: 'output',
-              id: 'abc123',
-              data: [],
+              type: 'outputs',
+              children: [
+                {
+                  type: 'output',
+                  id: 'abc123',
+                  jupyter_data: null,
+                  children: [],
+                },
+              ],
             },
           ],
         },
       ],
     };
-    expect(mdast.children[0].children.length).toEqual(2);
     reduceOutputs(new Session(), mdast, 'notebook.ipynb', '/my/folder');
-    expect(mdast.children[0].children.length).toEqual(1);
+    expect(mdast).toEqual({
+      type: 'root',
+      children: [
+        {
+          type: 'block',
+          children: [
+            {
+              type: 'paragraph',
+              children: [
+                {
+                  type: 'text',
+                  value: 'hi',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
   });
   it('output with complex data is removed', async () => {
     const mdast = {
@@ -49,18 +72,22 @@ describe('reduceOutputs', () => {
               ],
             },
             {
-              type: 'output',
+              type: 'outputs',
               id: 'abc123',
-              data: [
+              children: [
                 {
-                  output_type: 'display_data',
-                  execution_count: 3,
-                  metadata: {},
-                  data: {
-                    'application/octet-stream': {
-                      content_type: 'application/octet-stream',
-                      hash: 'def456',
-                      path: '/my/path/def456.png',
+                  type: 'output',
+                  children: [],
+                  jupyter_data: {
+                    output_type: 'display_data',
+                    execution_count: 3,
+                    metadata: {},
+                    data: {
+                      'application/octet-stream': {
+                        content_type: 'application/octet-stream',
+                        hash: 'def456',
+                        path: '/my/path/def456.png',
+                      },
                     },
                   },
                 },
@@ -72,9 +99,27 @@ describe('reduceOutputs', () => {
     };
     expect(mdast.children[0].children.length).toEqual(2);
     reduceOutputs(new Session(), mdast, 'notebook.ipynb', '/my/folder');
-    expect(mdast.children[0].children.length).toEqual(1);
+    expect(mdast).toEqual({
+      type: 'root',
+      children: [
+        {
+          type: 'block',
+          children: [
+            {
+              type: 'paragraph',
+              children: [
+                {
+                  type: 'text',
+                  value: 'hi',
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    });
   });
-  it('output is replaced with placeholder image', async () => {
+  it('outputs is replaced with placeholder image', async () => {
     const mdast = {
       type: 'root',
       children: [
@@ -91,9 +136,8 @@ describe('reduceOutputs', () => {
               ],
             },
             {
-              type: 'output',
+              type: 'outputs',
               id: 'abc123',
-              data: [],
               children: [
                 {
                   type: 'image',
@@ -108,11 +152,29 @@ describe('reduceOutputs', () => {
     };
     expect(mdast.children[0].children.length).toEqual(2);
     reduceOutputs(new Session(), mdast, 'notebook.ipynb', '/my/folder');
-    expect(mdast.children[0].children.length).toEqual(2);
-    expect(mdast.children[0].children[1]).toEqual({
-      type: 'image',
-      placeholder: true,
-      url: 'placeholder.png',
+    expect(mdast).toEqual({
+      type: 'root',
+      children: [
+        {
+          type: 'block',
+          children: [
+            {
+              type: 'paragraph',
+              children: [
+                {
+                  type: 'text',
+                  value: 'hi',
+                },
+              ],
+            },
+            {
+              type: 'image',
+              placeholder: true,
+              url: 'placeholder.png',
+            },
+          ],
+        },
+      ],
     });
   });
   // // These tests now require file IO...