Integrate @codama/spec@1.8.0

[lorisleiva]

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.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4596cd3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
@codama/nodes	Minor
@codama/cli	Patch
@codama/dynamic-codecs	Patch
@codama/dynamic-parsers	Patch
codama	Minor
@codama/nodes-from-anchor	Patch
@codama/renderers-core	Patch
@codama/validators	Minor
@codama/visitors-core	Minor
@codama/visitors	Minor
@codama/dynamic-address-resolution	Patch
@codama/dynamic-client	Patch
@codama/dynamic-instructions	Patch
@codama/errors	Minor
@codama/node-types	Minor
@codama/fragments	Patch

Not sure what this means? Click here to learn what changesets are.

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

[lorisleiva]

• Integrate @codama/spec@1.8.0 #1023 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[lorisleiva]

@trevor-cortex

[trevor-cortex]

Summary

Integrates @codama/spec@1.8.0 and threads the new pluginNode + json type expression through the TS reference implementation:

• @codama/node-types: adds PluginNode interface (kind: 'pluginNode', name: CamelCaseString, optional payload: unknown); adds it to the Node union; adds optional TPlugins generic + plugins? field on InstructionNode; bumps CodamaVersion to '1.8.0'.
• @codama/nodes: adds pluginNode(name, payload?) factory (freezes result, camelCases the name, omits payload when undefined); threads TPlugins through instructionNode; registers 'pluginNode' in REGISTERED_NODE_KINDS; bumps CODAMA_VERSION.
• @codama/spec-generators: bumps @codama/spec dep to 1.8.0; maps the new json type expression to unknown in both nodeTypes and nodes typeExpr fragments; registers pluginNode positional args (name, payload) in NODE_CONFIGS; appends plugins to the instruction generic-param order and to both merge/identity visitor walk orders.
• @codama/visitors-core: regenerates identityVisitor (recursively visits plugins, filters with 'pluginNode'), mergeVisitor (flatMaps plugins), and nodeTestPaths (adds pluginNode: 'PluginNode'). Adds a PluginNode.test.ts fixture covering merge/identity/deleteNodes/debugString.
• Changeset: @codama/nodes minor.

All additions are optional and backward-compatible with existing IDLs.

Things to watch out for

• Ordering is consistent everywhere. plugins is placed last in InstructionNode's generics, in GENERIC_PARAM_ORDER, in both MERGE_VISITOR_WALK_ORDER and IDENTITY_VISITOR_WALK_ORDER, and after display in the instructionNode factory spread. Good — matches the existing convention of appending new optional fields at the end.
• Opaque payload. pluginNode.payload is unknown by design (JSDoc: "Codama itself treats the payload as opaque"). It is not deep-frozen or cloned by the factory — consumers passing mutable objects will see them shared. That looks intentional given the "carried through the graph verbatim" contract, but worth noting for downstream renderers.
• Visitor filter tag. identityVisitor filters with removeNullAndAssertIsNodeFilter('pluginNode'), matching the registered kind — correct.
• Debug string. PluginNode hits the default branch of getDebugStringVisitor's getNodeDetails, which returns [node.name] since 'name' in node. So the test's expected pluginNode [anchor] is right, and no getDebugStringVisitor change is needed.
• json → unknown. Same mapping in both nodeTypes/fragments/typeExpr.ts and nodes/fragments/typeExpr.ts; consistent.

Notes for subsequent reviewers

• The packages/nodes and packages/visitors-core diffs are generated output — the source of truth is packages/spec-generators plus the pinned @codama/spec@1.8.0. Worth spot-checking that the regenerated files match what the generators would produce from a clean run, but structurally everything lines up.
• Consider whether a follow-up should extend getDebugStringVisitor's explicit switch to include 'pluginNode' (e.g. to also surface a payload marker), or leave it on the default branch as-is. Not a blocker.
• No renderer changes here; downstream renderers (renderers-js, renderers-rust, etc.) will need their own passes to actually consume plugins and json. Presumably tracked separately.

LGTM — clean, additive, and consistent with how other optional instruction fields (provides, display) were introduced.