[2.x] Add withPath and visitPath helpers to NodeStack

[lorisleiva]

This PR adds two helpers to NodeStack in @codama/visitors-core for jumping to another part of the tree, e.g. to the definition of a linked node.

• withPath(path, callback) runs callback with path as the current path and restores the previous one, even if callback throws.
• visitPath(path, visitor) visits the last node of path with the rest of path as the current path. The visited node is therefore recorded once, rather than twice as when the full path was pushed before visiting it.

The existing pushPath/popPath pairs in getByteSizeVisitor, getMaxByteSizeVisitor, getInstructionDataFields, unwrapDefinedTypesVisitor and dynamic-codecs now use these helpers.

[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
• [2.x] Adapt dynamic-parsers to Codama v2 #1187
• [2.x] Add withPath and visitPath helpers to NodeStack #1186 👈 (View in Graphite)
• [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 NodeStack.withPath(path, cb) and NodeStack.visitPath(path, visitor) to @codama/visitors-core and replaces the five hand-rolled pushPath/try/finally/popPath blocks across getByteSizeVisitor, getMaxByteSizeVisitor, getInstructionDataFields, unwrapDefinedTypesVisitor and dynamic-codecs with them. visitPath also fixes a subtle inaccuracy: the old callers pushed the full linked path and then visited its last node through a recordNodeStackVisitor-wrapped visitor, so the linked node appeared twice on the current path. It now appears once. New tests cover both helpers, including the throw/restore path.

The implementation is straightforward and I verified each call site picks the right helper: the three that visit the linked node itself through a stack-recording visitor use visitPath, and the two that descend into definedType.type directly (where the defined type genuinely belongs on the path) use withPath. No circular import is introduced (visitor.ts has no local imports), and the remaining visit / getLastNodeFromPath imports in the touched files are all still used.

Things to address

Missing changeset. CONTRIBUTING.md asks for a changeset for any user-facing change (npx changeset add --empty). This PR adds public API to @codama/visitors-core (which versions in the fixed core group) and changes the observable NodeStack contents while sizing/encoding a linked type in @codama/dynamic-codecs. I'd expect at least a minor for the new NodeStack methods; whether the dedup deserves its own patch entry for dynamic-codecs is your call, but it's worth a line since anyone reading stack.getPath() from a shared stack inside those visitors will see a different (correct) path.

README. packages/visitors-core/README.md → "Recording node paths" → NodeStack currently documents pushPath/popPath specifically for the "jump to a linked node and back" use case. Since withPath/visitPath are now the recommended way to do that, they should be added there (and the existing pushPath/popPath paragraph could point at them).

Notes for other reviewers

• The behavioural change (linked node recorded once instead of twice) is intentional and only affects consumers that read the stack while inside a linked type via a shared NodeStack. linkables.getPath(...) resolution relies on findProgramNodeFromPath, which is unaffected by the duplicate, so link resolution behaves identically before and after.
• visitPath's type signature (Visitor<TReturn, TNode['kind']> where TNode comes from NodePath<TNode>) accepts wider visitors, which is what makes the dynamic-codecs call with a Visitor<Codec, EncodableNodes['kind']> type-check against the linkable union.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 655bc94

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

[trevor-cortex]

Re-review

Both follow-ups from the previous pass landed:

• README — the NodeStack section now documents withPath/visitPath right after the pushPath/popPath example, including the "visitor must record on the same stack, otherwise use withPath" caveat. Reads well and matches the JSDoc on the methods.
• Test nit — the visitPath test now has recordNodeStackVisitor last in the pipe and asserts [root, root.program, slot, slot.type], which is a much clearer demonstration of the "recorded once" property.

The implementation itself is unchanged and still looks correct.

Still outstanding

Changeset. The changed-files list still contains nothing under .changeset/. CONTRIBUTING.md requires one for user-facing changes and this adds two public methods to @codama/visitors-core (fixed core group), so a minor entry is needed before merge. Optionally a patch line for @codama/dynamic-codecs noting the linked node is no longer duplicated on the stack.

That's the only blocker; happy to approve once the changeset is in.