Integrate @codama/spec@1.8.0 (#1023)

This PR integrates `@codama/spec@1.8.0`, threading the new `pluginNode` and `json` type expression through the TypeScript reference implementation. The node-types, nodes, and visitors-core packages are regenerated: `pluginNode` gains its interface and `pluginNode(name, payload?)` factory, `instructionNode` gains an optional `plugins` array, and the `json` type expression renders as `unknown`. A `PluginNode` visitor test fixture is added to satisfy the coverage gate. All changes are additive and optional.

Author: lorisleiva

.changeset/plugin-nodes.md

@@ -0,0 +1,5 @@
+---
+'@codama/nodes': minor
+---
+
+Integrate `@codama/spec@1.8.0`, adding the `pluginNode` to the node meta-model. A `pluginNode` attaches named, plugin-specific data to a node: it carries a `name` that uniquely identifies the plugin and an optional opaque `payload`. The payload is typed by the new `json` type expression, which renders as `unknown` in TypeScript. `instructionNode` gains an optional `plugins` field holding an array of `pluginNode`. All changes are additive and optional.

packages/node-types/src/generated/InstructionNode.ts

@@ -7,6 +7,7 @@ import type { InstructionArgumentNode } from './InstructionArgumentNode';
 import type { InstructionByteDeltaNode } from './InstructionByteDeltaNode';
 import type { InstructionRemainingAccountsNode } from './InstructionRemainingAccountsNode';
 import type { InstructionStatusNode } from './InstructionStatusNode';
+import type { PluginNode } from './PluginNode';
 import type { ProvidedNode } from './ProvidedNode';
 import type { OptionalAccountStrategy } from './shared/optionalAccountStrategy';
 
@@ -26,6 +27,7 @@ export interface InstructionNode<
     TStatus extends InstructionStatusNode | undefined = InstructionStatusNode | undefined,
     TProvides extends Array<ProvidedNode> | undefined = Array<ProvidedNode> | undefined,
     TDisplay extends InstructionDisplayNode | undefined = InstructionDisplayNode | undefined,
+    TPlugins extends Array<PluginNode> | undefined = Array<PluginNode> | undefined,
 > {
     readonly kind: 'instructionNode';
 
@@ -64,4 +66,6 @@ export interface InstructionNode<
     readonly provides?: TProvides;
     /** Display metadata describing how the instruction is presented. */
     readonly display?: TDisplay;
+    /** Namespaced plugins with custom structured data. */
+    readonly plugins?: TPlugins;
 }

packages/node-types/src/generated/Node.ts

@@ -16,6 +16,7 @@ import type { InstructionStatusNode } from './InstructionStatusNode';
 import type { RegisteredLinkNode } from './linkNodes/RegisteredLinkNode';
 import type { PdaNode } from './PdaNode';
 import type { RegisteredPdaSeedNode } from './pdaSeedNodes/RegisteredPdaSeedNode';
+import type { PluginNode } from './PluginNode';
 import type { ProgramNode } from './ProgramNode';
 import type { ProvidedNode } from './ProvidedNode';
 import type { RootNode } from './RootNode';
@@ -37,6 +38,7 @@ export type Node =
     | InstructionRemainingAccountsNode
     | InstructionStatusNode
     | PdaNode
+    | PluginNode
     | ProgramNode
     | ProvidedNode
     | RegisteredContextualValueNode

packages/node-types/src/generated/PluginNode.ts

@@ -0,0 +1,15 @@
+import type { CamelCaseString } from '../brands';
+
+/**
+ * Attaches named, plugin-specific data to a node.
+ * A plugin is uniquely identified by its `name`; the optional `payload` carries arbitrary, consumer-defined data that only the matching plugin knows how to interpret. Codama itself treats the payload as opaque.
+ */
+export interface PluginNode {
+    readonly kind: 'pluginNode';
+
+    // Data.
+    /** The unique name identifying the plugin this data belongs to. */
+    readonly name: CamelCaseString;
+    /** Arbitrary, plugin-specific data. Its shape is defined by the plugin, not by Codama, and is carried through the graph verbatim. */
+    readonly payload?: unknown;
+}

packages/node-types/src/generated/index.ts

@@ -13,6 +13,7 @@ export * from './InstructionRemainingAccountsValue';
 export * from './InstructionStatusNode';
 export * from './Node';
 export * from './PdaNode';
+export * from './PluginNode';
 export * from './ProgramNode';
 export * from './ProvidedNode';
 export * from './RootNode';

packages/node-types/src/generated/shared/codamaVersion.ts

@@ -3,4 +3,4 @@
  * version of the spec at generation time; documents conforming to this
  * version of the spec carry this exact string.
  */
-export type CodamaVersion = '1.7.0';
+export type CodamaVersion = '1.8.0';

packages/nodes/src/generated/InstructionNode.ts

@@ -7,6 +7,7 @@ import type {
     InstructionNode,
     InstructionRemainingAccountsNode,
     InstructionStatusNode,
+    PluginNode,
     ProvidedNode,
 } from '@codama/node-types';
 import { camelCase, DocsInput, parseDocs } from '../shared';
@@ -24,6 +25,7 @@ export type InstructionNodeInput<
     TStatus extends InstructionStatusNode | undefined = InstructionStatusNode | undefined,
     TProvides extends Array<ProvidedNode> | undefined = Array<ProvidedNode> | undefined,
     TDisplay extends InstructionDisplayNode | undefined = InstructionDisplayNode | undefined,
+    TPlugins extends Array<PluginNode> | undefined = Array<PluginNode> | undefined,
 > = Omit<
     Partial<
         InstructionNode<
@@ -36,7 +38,8 @@ export type InstructionNodeInput<
             TSubInstructions,
             TStatus,
             TProvides,
-            TDisplay
+            TDisplay,
+            TPlugins
         >
     >,
     'docs' | 'kind' | 'name'
@@ -57,6 +60,7 @@ export function instructionNode<
     const TStatus extends InstructionStatusNode | undefined = undefined,
     const TProvides extends Array<ProvidedNode> | undefined = undefined,
     const TDisplay extends InstructionDisplayNode | undefined = undefined,
+    const TPlugins extends Array<PluginNode> | undefined = undefined,
 >(
     input: InstructionNodeInput<
         TAccounts,
@@ -68,7 +72,8 @@ export function instructionNode<
         TSubInstructions,
         TStatus,
         TProvides,
-        TDisplay
+        TDisplay,
+        TPlugins
     >,
 ): InstructionNode<
     TAccounts,
@@ -80,7 +85,8 @@ export function instructionNode<
     TSubInstructions,
     TStatus,
     TProvides,
-    TDisplay
+    TDisplay,
+    TPlugins
 > {
     const parsedDocs = parseDocs(input.docs);
     return Object.freeze({
@@ -102,5 +108,6 @@ export function instructionNode<
         ...(input.subInstructions !== undefined && { subInstructions: input.subInstructions }),
         ...(input.provides !== undefined && { provides: input.provides }),
         ...(input.display !== undefined && { display: input.display }),
+        ...(input.plugins !== undefined && { plugins: input.plugins }),
     });
 }

packages/nodes/src/generated/PluginNode.ts

@@ -0,0 +1,16 @@
+import type { PluginNode } from '@codama/node-types';
+import { camelCase } from '../shared';
+
+/**
+ * Attaches named, plugin-specific data to a node.
+ * A plugin is uniquely identified by its `name`; the optional `payload` carries arbitrary, consumer-defined data that only the matching plugin knows how to interpret. Codama itself treats the payload as opaque.
+ */
+export function pluginNode(name: string, payload?: unknown): PluginNode {
+    return Object.freeze({
+        kind: 'pluginNode',
+
+        // Data.
+        name: camelCase(name),
+        ...(payload !== undefined && { payload }),
+    });
+}

packages/nodes/src/generated/codamaVersion.ts

@@ -8,4 +8,4 @@ import type { CodamaVersion } from '@codama/node-types';
  * that need to compare an IDL document's `version` against the spec
  * shape `@codama/nodes` understands.
  */
-export const CODAMA_VERSION: CodamaVersion = '1.7.0';
+export const CODAMA_VERSION: CodamaVersion = '1.8.0';

packages/nodes/src/generated/index.ts

@@ -14,6 +14,7 @@ export * from './InstructionRemainingAccountsValue';
 export * from './InstructionStatusNode';
 export * from './nodeKinds';
 export * from './PdaNode';
+export * from './PluginNode';
 export * from './ProgramNode';
 export * from './ProvidedNode';
 export * from './RootNode';