impr: Better metadata versioning

[iwoplaza]

When unplugin-typegpu embeds metadata into source code, it does so with a single-number version:

const metadata = `{
  v: ${FORMAT_VERSION},
  name: ${name ? `"${name}"` : 'undefined'},
  ast: ${embedJSON(ast)},
  externals: () => ({${ast.externalNames
    .map((e) => (e === 'this' ? '"this": this' : e))
    .join(', ')}}),
}`;

FORMAT_VERSION is a number imported from tinyest, and directly relates to possible changes in the tinyest representation, which would allow us to distinguish how to interpret the metadata if we choose to update that format in the future. There are cases where we want to update other parts of the metadata though, like the recent #2019 workload.

Proposal

I propose we reinterpret this v property as the version of the metadata as a whole, not just tinyest. We can interpret 1 as being the current form, and use 2 when emitting the changed externals format introduced in #2019.

const METADATA_FORMAT_VERSION = 2;

const metadata = `{
  v: ${METADATA_FORMAT_VERSION},
  name: ${name ? `"${name}"` : 'undefined'},
  ast: ${embedJSON(ast)},
  externals: /* ... */,
}`;

We can then have a normalizeMetadata function in the typegpu package that accepts both versions, and returns a common data structure that is used by the rest of the program.

interface RawMetadata1 {
  v: 1;
  // ...
}

interface RawMetadata2 {
  v: 2;
  // ...
}

type RawMetadata = RawMetadata1 | RawMetadata2;

interface Metadata {
  // ...
}

function normalizeMetadata(meta: RawMetadata): Metadata {
  if (meta.v === 1) {
    // ...
  }

  if (meta.v === 2) {
    // ...
  }

  throw new Error(`Unrecognized TypeGPU metadata format: ${JSON.stringify(meta)}`);
}

[aleksanderkatan]

Looks good! It fits nicely with what is currently happening #2425

let pluginExternals: ExternalMap | Record<string, unknown> | undefined =
  pluginData?.externals2
    ? externals2ToExternalMap(pluginData.externals2)
    : typeof pluginData?.externals === 'function'
      ? pluginData.externals()
      : pluginData?.externals;

We already kind of had 2 versions: with or without () => in externals, though we can keep both as the v: 1 variants