🪓 Split Output into Outputs -> Output[]

[agoose77]

Warning

Please do not review this PR. It's a proof-of-concept to illustrate conversation.

This PR is an alternative to #1661 that attempts to solve #1026. It does the following:

1. Introduces a distinction between internal AST and external AST.
2. Upgrades external AST into internal AST (e.g. pulling in xref).
3. Downgrades internal AST to external AST (e.g. on writing to disk).

Tip

Internal AST is the AST that our transforms (and plugins) operate upon.
External AST is the AST that we publish to e.g. the web.
The factoring of our AST into two "branches" means that we can defer breaking changes to an arbitrary point in the future.

New Internal AST Form

The internal AST has the following form:

type CodeBlock = {
  type: "block";
  kind: "notebook-code",
  children: [
    Code,
    Outputs
  ]
}

type Outputs = {
  type: "outputs";
  children: Output[];
  visibility: ...;
  identifier: ...;
  html_id: ...;
}

type Output = {
  type: "output";
  children: GenericNode[];
  jupyter_data: IOutput;
}

New External AST Form

type CodeBlock = {
  type: "block";
  kind: "notebook-code",
  children: [
    Code,
    Output
  ]
}
type Output = {
  type: "output";
  children: GenericNode[];
  data: IOutput[];
  _future_ast: JSONString<Outputs>
}

In this PR, I don't break our published AST at all by storing a "replacement" AST as JSON in a node field.

Note

The pattern of _future_ast replacing the current node seems like it might be quite useful. A way to systematically define forwards-compatible AST.

Closes #1674

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1f3a8c2

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[agoose77]

Not certain of the purpose of id, but I suspect we actually want to lift this up.