fix(validators): make recordNodeStackVisitor follow prefix traversal rules

getValidationItemsVisitor was the only visitor to run its per-node logic before
committing the current node to the stack, so validation ran in the gap between
arriving at a node and recording it. Two bugs fell out of that single ordering:

  - visitDefinedTypeLink calls stack.getPath(node.kind), which asserts the top
    of the stack is the link node; the link node was not committed yet, so the
    top was its parent, and any nested definedTypeLink (struct field, argument,
    array, PDA seed) threw `Expected node of kind [definedTypeLinkNode]`. Six of
    this repo's own test IDLs hit it, including example-idl.json, System, Token,
    and Token-2022.
  - every validationItem recorded an ancestors-only path, missing the node
    itself, which contradicts the documented ValidationItem.path contract
    ("the path of nodes that led to the node above, including the node itself").

Commit the node before the per-node logic runs, matching the eleven other
recordNodeStackVisitor consumers (getByteSizeVisitor, and the rest): the node
is on the stack when the visit runs, so getPath(node.kind) resolves, missing
links are reported instead of throwing, and recorded paths satisfy the
contract. The two existing tests asserted the off-by-one paths, so they are
corrected to the documented behaviour.

Author: cds-amal

.changeset/fix-validator-nested-defined-type-link.md

@@ -0,0 +1,5 @@
+---
+'@codama/validators': patch
+---
+
+Fix `getValidationItemsVisitor` throwing `Expected node of kind [definedTypeLinkNode]` on any nested `definedTypeLinkNode` (a struct field, argument, array element, or PDA seed), and recording `ValidationItem` paths that omitted the node itself. The visitor now composes `recordNodeStackVisitor` outermost, like every other visitor, so the current node is on the stack when validation runs.

packages/validators/src/getValidationItemsVisitor.ts

@@ -23,8 +23,6 @@ export function getValidationItemsVisitor(): Visitor<readonly ValidationItem[]>
             () => [] as readonly ValidationItem[],
             (_, items) => items.flat(),
         ),
-        v => recordLinkablesOnFirstVisitVisitor(v, linkables),
-        v => recordNodeStackVisitor(v, stack),
         v =>
             extendVisitor(v, {
                 visitAccount(node, { next }) {
@@ -243,5 +241,11 @@ export function getValidationItemsVisitor(): Visitor<readonly ValidationItem[]>
                     return [...items, ...next(node)];
                 },
             }),
+        // Pipe stages run outermost-first, i.e. in reverse of their listing here:
+        //   pipe(init, g, h, i) => i(h(g(init)))   -- i is the outer layer, runs first
+        // so these record the node (onto the stack, and into linkables) BEFORE the
+        // extendVisitor logic above runs and reads that state to validate the node.
+        v => recordNodeStackVisitor(v, stack),
+        v => recordLinkablesOnFirstVisitVisitor(v, linkables),
     );
 }

packages/validators/test/getValidationItemsVisitor.test.ts

@@ -32,10 +32,10 @@ test('it validates program nodes', () => {
 
     // Then we expect the following validation errors.
     expect(items).toEqual([
-        validationItem('error', 'Program has no name.', node, []),
-        validationItem('error', 'Program has no public key.', node, []),
-        validationItem('warn', 'Program has no version.', node, []),
-        validationItem('info', 'Program has no origin.', node, []),
+        validationItem('error', 'Program has no name.', node, [node]),
+        validationItem('error', 'Program has no public key.', node, [node]),
+        validationItem('warn', 'Program has no version.', node, [node]),
+        validationItem('info', 'Program has no origin.', node, [node]),
     ]);
 });
 
@@ -56,8 +56,8 @@ test('it validates nested nodes', () => {
     const tupleNode = node.items[0];
     const structNode = node.items[1];
     expect(items).toEqual([
-        validationItem('warn', 'Tuple has no items.', tupleNode, [node]),
-        validationItem('error', 'Struct field name "owner" is not unique.', structNode.fields[0], [node]),
+        validationItem('warn', 'Tuple has no items.', tupleNode, [node, tupleNode]),
+        validationItem('error', 'Struct field name "owner" is not unique.', structNode.fields[0], [node, structNode]),
     ]);
 });