[2.x] Add resolveTypePath helper to visitors-core

[lorisleiva]

This PR adds resolveTypePath to @codama/visitors-core, which resolves a path expression such as config.fees[0] against a type and returns the full NodePath of the node it points to.

• Field segments select struct fields and index segments select tuple items or the items of arrays and sets.
• Struct fields, enum variants and definedTypeLinkNodes along the way resolve to their types, following links through the path of their definitions so subsequent links resolve in the right program. The last node is returned as addressed.
• Adds the generic CANNOT_RESOLVE_PATH error, thrown when a segment of a path expression cannot be followed, and throws LINKED_NODE_NOT_FOUND for dangling links.
• Moves parsePath from @codama/visitors to @codama/visitors-core and documents both helpers in the README.

@codama/dynamic-parsers now uses it to resolve fieldDiscriminatorNode paths, attaching the CANNOT_RESOLVE_PATH error as the cause of DISCRIMINATOR_FIELD_NOT_FOUND.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 145c154

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]

@trevor-cortex

[lorisleiva]

• [2.x] Adapt the dynamic-instructions builder to Codama v2 #1194
• [2.x] Reject values of the wrong type when encoding dynamic codecs #1193
• [2.x] Adapt dynamic-address-resolution to Codama v2 #1192
• [2.x] Accept bytes, enum shorthands and struct defaults when encoding dynamic codecs #1191
• [2.x] Add resolveTypePath helper to visitors-core #1190 👈 (View in Graphite)
• [2.x] Adapt dynamic-parsers to Codama v2 #1187
• [2.x] Add withPath and visitPath helpers to NodeStack #1186
• [2.x] Adapt dynamic-codecs to Codama v2 #1185
• [2.x] Add relations, nested argument seeds and legacy PDAs to nodes-from-anchor #1181
• [2.x] Adapt nodes-from-anchor to Codama v2 #1180
• [2.x] Adapt instruction visitors to Codama v2 #1179
• [2.x] Adapt update visitors to Codama v2 #1178
• [2.x] Adapt structure visitors to Codama v2 #1175
• [2.x] Move casing helpers to @codama/fragments #1174
• [2.x] Adapt validators to Codama v2 #1173
• [2.x] Adapt visitors-core to Codama v2 #1172
• [2.x] Adapt nodes to Codama v2 #1171
• [2.x] Adapt errors to Codama v2 #1167
• [2.x] Rename node name attribute to identifier #1162
• [2.x] Regenerate the node types from the v2 spec #1158
• main

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

[trevor-cortex]

Summary

Adds resolveTypePath(source, path, linkables) to @codama/visitors-core: it walks a PathString (config.fees[0]) from the type at the end of source, transparently resolving struct fields / enum variants / definedTypeLinkNodes to their underlying type between segments, and returns the full NodePath of the addressed node. Links are followed through the definition's path so nested links resolve in the defining program, alias cycles are detected via a per-segment Set<DefinedTypeNode>, and failures surface as the new generic CANNOT_RESOLVE_PATH (with nodePath / path / segment context) or the existing LINKED_NODE_NOT_FOUND. parsePath + PathSegment move from @codama/visitors (where they weren't publicly exported) into visitors-core, and @codama/dynamic-parsers replaces its bespoke findDataField with the helper, wrapping CANNOT_RESOLVE_PATH as the cause of DISCRIMINATOR_FIELD_NOT_FOUND and rejecting non-struct-field results (e.g. pair[0]).

The implementation is clean and the semantics are well pinned down by tests (cross-program link following, "last node returned as addressed", per-segment error contexts, dangling links, alias cycles). The dynamic-parsers migration is behaviour-preserving for the previously supported cases and strictly more informative on failure. The types line up: RegisteredTypeNode = EnumVariantTypeNode | StandaloneTypeNode | StructFieldTypeNode in 2.x, so TypePathNode = DefinedTypeLinkNode | RegisteredTypeNode covers exactly the set resolveContainer knows how to unwrap.

Things to address

• Missing changeset. CONTRIBUTING.md asks for one on any user-facing change, and this PR has several: a new public export in @codama/visitors-core (resolveTypePath, parsePath, PathSegment, TypePath, TypePathNode), a new error code in @codama/errors, and the cause/tuple-item behaviour change in @codama/dynamic-parsers. visitors-core and errors are in the fixed group so one entry covers both; dynamic-parsers versions independently and probably wants its own line. Happy to approve once that's in.
• Import member ordering in packages/dynamic-parsers/src/discriminators.ts, packages/dynamic-parsers/test/discriminators.test.ts (L6) and packages/visitors-core/test/resolveTypePath.test.ts (L1): CODAMA_ERROR__CANNOT_RESOLVE_PATH is inserted after DISCRIMINATOR_* / LINKED_NODE_NOT_FOUND rather than alphabetically. packages/errors/src/context.ts and messages.ts have it in the right place. Every other import block in these files is case-insensitively sorted, so I'd expect oxlint to flag this — pnpm lint:fix should sort it out. (Inline comment on the first occurrence only.)

Non-blocking notes

• createPathResolver.rewrite in packages/visitors/src/updateHelpers.ts still hand-rolls the same walk (link following via linkables.getPath, followedDefinedTypes cycle set, tuple/array/set indexing). It can't just call resolveTypePath because it needs per-segment owner/prefix bookkeeping and must be lenient rather than throw, so I don't think this PR should touch it — but it's now the second copy of the stepping logic. If a third consumer shows up, exposing a per-segment step (resolveContainer + one segment application) from resolveTypePath.ts would let rewrite reuse it.
• Array/set indices aren't bounds-checked against fixedCountNode ([5] on a 2-element array resolves to the item). That matches rewrite and the README wording ("the item of an array or set"), so I assume it's deliberate; left a one-line docblock nit inline.

Notes for subsequent reviewers

• The dynamic-parsers change keeps context.stack.withPath(resolved, …) semantics identical: the old findDataField also switched to the linked definition's path when it followed a link, so codec resolution inside the discriminator field's type still happens in the defining program.
• expectCodamaError in the new test file compares error.context with toStrictEqual, which is sufficient to also assert the error code since CodamaError stores __code in context.
• parsePath was only ever exported from updateHelpers.ts, not from the @codama/visitors barrel, so the move is additive rather than breaking.