[2.x] Make NodePath non-distributive over node unions

[lorisleiva]

This PR stops NodePath from splitting node unions into one path type per member:

NodePath<AccountNode | PdaNode>
// before: readonly [...Node[], AccountNode] | readonly [...Node[], PdaNode]
// after:  readonly [...Node[], AccountNode | PdaNode]

The new type is strictly wider, so existing paths still type-check. It also accepts paths built from a node only known as a union, such as [...stack.getPath(), node], which previously didn't compile against NodePath<Node>. The one thing it no longer does is fit a parameter typed as an explicit union of paths, e.g. NodePath<AccountNode> | NodePath<PdaNode>. Such parameters should use NodePath<AccountNode | PdaNode> instead.

The conditional still distributes over the node type to tell NodePath (any list of nodes) apart from NodePath<T>, but every path now ends at the whole node type. A plain [TNode] extends [undefined] check would have left NodePath<T> unresolved for generic node types, e.g. in LinkableDictionary.

undefined is excluded from the last node, so NodePath<PdaNode | undefined> remains readonly Node[] | readonly [...Node[], PdaNode].

A new NodePath.test.ts covers union, single-kind, untyped and optional paths. Its union assertion fails to compile with the previous type.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4f94500

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

[lorisleiva]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [2.x] Format decoded nodes into formatted node trees #1218
• [2.x] Add formatters for booleans, bytes, enums and public keys #1217
• [2.x] Return decoded nodes from dynamic parsers #1216
• [2.x] Add formatters for decoded nodes #1215
• [2.x] Decode Codama nodes into decoded node trees #1214
• [2.x] Report defined types without a finite value in validators #1213
• [2.x] Support recursive defined types in dynamic codecs #1212
• [2.x] Detect cyclic defined types #1211
• [2.x] Port the dynamic client to Codama v2 #1209
• [2.x] Reject duplicate set items in dynamic codecs #1208
• [2.x] Upgrade v1 instructions, programs and roots to v2 #1207
• [2.x] Keep the cause of validation items and drop their node #1206
• [2.x] Make NodePath non-distributive over node unions #1205 👈 (View in Graphite)
• [2.x] Use the published v1 node types in @codama/upgrade #1201
• [2.x] Add v1 to v2 upgrade converters for types and values #1200
• [2.x] Adapt to spec 2.0.0-rc.1 #1196
• main

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

[lorisleiva]

@trevor-cortex

[trevor-cortex]

Summary

Makes NodePath<TNode> non-distributive over the node type: NodePath<A | B> is now a single readonly [...Node[], A | B] tuple instead of NodePath<A> | NodePath<B>. The trick is the NodePathImpl<TCheck, TNode> indirection: the conditional still distributes over TCheck (so undefined members still resolve to readonly Node[] and generic TNodes stay deferred rather than collapsing), but the tail element reads from the second, non-checked parameter, which TS does not substitute per-member. Exclude<TNode, undefined> is needed precisely because TNode is the whole union in that branch. Adds a type-level test file.

I walked through the four cases (undefined, single kind, union, X | undefined) plus the generic TLinkNode path in LinkableDictionary and the predicate narrowing in recordPath (isNodePath(linkablePath, 'accountNode') now narrows a single tuple type to a subtype rather than filtering a union — assignable, so it still works). The implementation is correct and the doc comments explain the non-obvious parts well.

A nice side effect worth knowing about: NodePath<Node> used to expand to a ~70-member union of tuple types; it's now one tuple. That should help both compile times and error messages wherever isFilledNodePath / NodePath<Node> show up.

Before merging

• Changeset. CONTRIBUTING.md asks for a changeset on any user-facing change, and this changes a public exported type with a consumer-visible caveat (parameters typed NodePath<A> | NodePath<B> no longer accept a NodePath<A | B> argument). A patch for @codama/visitors-core (the fixed core group handles the rest) with a one-liner mirroring the PR description seems right. If the 2.x branch policy deliberately skips changesets for type-only changes, ignore this.

Notes for other reviewers

• The only possible regression is the one named in the description: any parameter typed as an explicit union of paths. Nothing in visitors-core does that, and pnpm test:types across the monorepo is the real guard here. It's worth a quick grep for NodePath<\w+> \| in the downstream renderers (renderers-js, renderers-rust, renderers-core) before the next release, since a stack.getPath(['accountNode', 'definedTypeNode']) result would now be rejected by such a parameter.
• Inference of TNode in getLastNodeFromPath / NodeStack.visitPath now goes through Exclude<TNode, undefined> instead of a bare TNode in the tuple tail. The test on getLastNodeFromPath(path) returning AccountNode | PdaNode confirms inference still resolves through it.