@eslint/plugin-kit 0.4.1: VisitNodeStep

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify @eslint/plugin-kit.VisitNodeStep in pkg:npm/%40eslint/plugin-kit@0.4.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40eslint/plugin-kit@0.4.1
Demonstrate these symbols/APIs:
  - @eslint/plugin-kit.VisitNodeStep

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:173737318ed932e426a09825d2f3a308c995556bb461108c0a7e130840006a0d","contract":["assert VisitNodeStep constructor initializes type 'visit' and kind 1","assert VisitNodeStep stores target, phase 1 (enter) and phase 2 (exit), and args array","assert createEnterStep and createExitStep produce valid VisitNodeStep instances","assert isVisitNodeStep identifies VisitNodeStep instances","assert dispatchVisitStep executes enter and exit visitor hooks","assert traverseAst yields balanced enter and exit VisitNodeStep traversal steps"],"goal":"verify @eslint/plugin-kit.VisitNodeStep in pkg:npm/%40eslint/plugin-kit@0.4.1","kind":"HOW","packages":["pkg:npm/%40eslint/plugin-kit@0.4.1"],"schemaVersion":1,"symbols":["@eslint/plugin-kit.VisitNodeStep"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40eslint/plugin-kit@0.4.1"],"schemaVersion":1,"subject":"pkg:npm/%40eslint/plugin-kit@0.4.1","symbols":["@eslint/plugin-kit.VisitNodeStep"],"verifierAdapter":"node-typescript@1"}

const { VisitNodeStep } = require('@eslint/plugin-kit');

/**
 * Creates a VisitNodeStep instance representing entering an AST node.
 *
 * @param {object} target - The AST node being entered.
 * @param {Array<any>} [args=[]] - Additional arguments passed to visitors.
 * @returns {VisitNodeStep} Step instance with phase 1.
 */
function createEnterStep(target, args = [target]) {
  return new VisitNodeStep({ target, phase: 1, args });
}

/**
 * Creates a VisitNodeStep instance representing exiting an AST node.
 *
 * @param {object} target - The AST node being exited.
 * @param {Array<any>} [args=[]] - Additional arguments passed to visitors.
 * @returns {VisitNodeStep} Step instance with phase 2.
 */
function createExitStep(target, args = [target]) {
  return new VisitNodeStep({ target, phase: 2, args });
}

/**
 * Type guard / validator to check if an object is a VisitNodeStep.
 *
 * @param {unknown} step - Object to inspect.
 * @returns {boolean} True if the step is a valid VisitNodeStep.
 */
function isVisitNodeStep(step) {
  return (
    step instanceof VisitNodeStep ||
    (typeof step === 'object' &&
      step !== null &&
      step.type === 'visit' &&
      step.kind === 1 &&
      typeof step.target === 'object' &&
      (step.phase === 1 || step.phase === 2) &&
      Array.isArray(step.args))
  );
}

/**
 * Dispatches a VisitNodeStep to a visitor object.
 *
 * @param {VisitNodeStep} step - The traversal step to dispatch.
 * @param {object} visitor - An object containing visitor methods.
 * @returns {any} Result of the visitor invocation, if any.
 */
function dispatchVisitStep(step, visitor) {
  if (!isVisitNodeStep(step)) {
    throw new TypeError('Expected a VisitNodeStep instance');
  }

  const { target, phase, args } = step;
  const nodeType = target.type || 'Node';

  if (phase === 1) {
    if (typeof visitor[nodeType] === 'function') {
      return visitor[nodeType](...args);
    }
    if (typeof visitor.enter === 'function') {
      return visitor.enter(...args);
    }
  } else if (phase === 2) {
    const exitKey = `${nodeType}:exit`;
    if (typeof visitor[exitKey] === 'function') {
      return visitor[exitKey](...args);
    }
    if (typeof visitor.exit === 'function') {
      return visitor.exit(...args);
    }
  }

  return undefined;
}

/**
 * Generator that traverses an AST and yields VisitNodeStep instances for each node.
 *
 * @param {object} node - Root AST node to traverse.
 * @param {object|null} [parent=null] - Parent AST node.
 * @yields {VisitNodeStep} Traversal steps for node entry and exit.
 */
function* traverseAst(node, parent = null) {
  if (!node || typeof node !== 'object') {
    return;
  }

  yield createEnterStep(node, [node, parent]);

  for (const [key, value] of Object.entries(node)) {
    if (key === 'parent' || key === 'loc' || key === 'range') {
      continue;
    }
    if (Array.isArray(value)) {
      for (const item of value) {
        if (item && typeof item === 'object' && typeof item.type === 'string') {
          yield* traverseAst(item, node);
        }
      }
    } else if (value && typeof value === 'object' && typeof value.type === 'string') {
      yield* traverseAst(value, node);
    }
  }

  yield createExitStep(node, [node, parent]);
}

module.exports = {
  VisitNodeStep,
  createEnterStep,
  createExitStep,
  isVisitNodeStep,
  dispatchVisitStep,
  traverseAst,
};

{
  "name": "sample-eslint-plugin-kit-visit-node-step",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-eslint-plugin-kit-visit-node-step",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@eslint/plugin-kit": "0.4.1"
      }
    },
    "node_modules/@eslint/core": {
      "version": "0.17.0",
      "resolved": "https://registry.npmjs.org/@eslint/core/-/core-0.17.0.tgz",
      "integrity": "sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "@types/json-schema": "^7.0.15"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      }
    },
    "node_modules/@eslint/plugin-kit": {
      "version": "0.4.1",
      "resolved": "https://registry.npmjs.org/@eslint/plugin-kit/-/plugin-kit-0.4.1.tgz",
      "integrity": "sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==",
      "license": "Apache-2.0",
      "dependencies": {
        "@eslint/core": "^0.17.0",
        "levn": "^0.4.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      }
    },
    "node_modules/@types/json-schema": {
      "version": "7.0.15",
      "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
      "integrity": "sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==",
      "license": "MIT"
    },
    "node_modules/levn": {
      "version": "0.4.1",
      "resolved": "https://registry.npmjs.org/levn/-/levn-0.4.1.tgz",
      "integrity": "sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==",
      "license": "MIT",
      "dependencies": {
        "prelude-ls": "^1.2.1",
        "type-check": "~0.4.0"
      },
      "engines": {
        "node": ">= 0.8.0"
      }
    },
    "node_modules/prelude-ls": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
      "integrity": "sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.8.0"
      }
    },
    "node_modules/type-check": {
      "version": "0.4.0",
      "resolved": "https://registry.npmjs.org/type-check/-/type-check-0.4.0.tgz",
      "integrity": "sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==",
      "license": "MIT",
      "dependencies": {
        "prelude-ls": "^1.2.1"
      },
      "engines": {
        "node": ">= 0.8.0"
      }
    }
  }
}

{
  "name": "sample-eslint-plugin-kit-visit-node-step",
  "version": "1.0.0",
  "description": "Clean-room sample verifying @eslint/plugin-kit.VisitNodeStep",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "@eslint/plugin-kit": "0.4.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify @eslint/plugin-kit.VisitNodeStep in pkg:npm/%40eslint/plugin-kit@0.4.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40eslint/plugin-kit@0.4.1"
  ],
  "symbols": [
    "@eslint/plugin-kit.VisitNodeStep"
  ]
}

import assert from 'node:assert';
import {
  VisitNodeStep,
  createEnterStep,
  createExitStep,
  isVisitNodeStep,
  dispatchVisitStep,
  traverseAst,
} from '../index.js';

// 1. Verify VisitNodeStep class constructor and default properties
const literalNode = { type: 'Literal', value: 42 };
const step1 = new VisitNodeStep({
  target: literalNode,
  phase: 1,
  args: [literalNode, null],
});

assert.strictEqual(step1.type, 'visit');
assert.strictEqual(step1.kind, 1);
assert.strictEqual(step1.phase, 1);
assert.strictEqual(step1.target, literalNode);
assert.deepStrictEqual(step1.args, [literalNode, null]);

// 2. Verify exit phase step construction
const parentNode = { type: 'ExpressionStatement', expression: literalNode };
const step2 = new VisitNodeStep({
  target: literalNode,
  phase: 2,
  args: [literalNode, parentNode],
});

assert.strictEqual(step2.type, 'visit');
assert.strictEqual(step2.kind, 1);
assert.strictEqual(step2.phase, 2);
assert.strictEqual(step2.target, literalNode);
assert.strictEqual(step2.args[0], literalNode);
assert.strictEqual(step2.args[1], parentNode);

// 3. Verify helper step creators
const enterStep = createEnterStep(literalNode, [literalNode, parentNode]);
assert.ok(enterStep instanceof VisitNodeStep);
assert.strictEqual(enterStep.phase, 1);
assert.strictEqual(enterStep.type, 'visit');
assert.strictEqual(enterStep.kind, 1);

const exitStep = createExitStep(literalNode, [literalNode, parentNode]);
assert.ok(exitStep instanceof VisitNodeStep);
assert.strictEqual(exitStep.phase, 2);
assert.strictEqual(exitStep.type, 'visit');
assert.strictEqual(exitStep.kind, 1);

// 4. Verify isVisitNodeStep identification
assert.strictEqual(isVisitNodeStep(step1), true);
assert.strictEqual(isVisitNodeStep(step2), true);
assert.strictEqual(isVisitNodeStep(enterStep), true);
assert.strictEqual(isVisitNodeStep(exitStep), true);
assert.strictEqual(isVisitNodeStep(null), false);
assert.strictEqual(isVisitNodeStep({}), false);
assert.strictEqual(isVisitNodeStep({ type: 'call', kind: 2 }), false);

// 5. Verify dispatchVisitStep executes visitor enter and exit hooks
const trace = [];
const visitor = {
  enter(node) {
    trace.push(`generic:enter:${node.type}`);
  },
  Literal(node) {
    trace.push(`Literal:enter:${node.value}`);
  },
  'Literal:exit'(node) {
    trace.push(`Literal:exit:${node.value}`);
  },
  exit(node) {
    trace.push(`generic:exit:${node.type}`);
  },
};

dispatchVisitStep(step1, visitor);
assert.deepStrictEqual(trace, ['Literal:enter:42']);

dispatchVisitStep(step2, visitor);
assert.deepStrictEqual(trace, ['Literal:enter:42', 'Literal:exit:42']);

// Dispatch with fallback generic enter/exit
const identNode = { type: 'Identifier', name: 'count' };
const identEnter = createEnterStep(identNode, [identNode, null]);
const identExit = createExitStep(identNode, [identNode, null]);

dispatchVisitStep(identEnter, visitor);
assert.strictEqual(trace[2], 'generic:enter:Identifier');

dispatchVisitStep(identExit, visitor);
assert.strictEqual(trace[3], 'generic:exit:Identifier');

// 6. Verify traverseAst yields VisitNodeStep instances across AST hierarchy
const sampleAst = {
  type: 'Program',
  body: [
    {
      type: 'VariableDeclaration',
      kind: 'const',
      declarations: [
        {
          type: 'VariableDeclarator',
          id: { type: 'Identifier', name: 'greeting' },
          init: { type: 'Literal', value: 'hello' },
        },
      ],
    },
  ],
};

const steps = Array.from(traverseAst(sampleAst));
assert.ok(steps.length > 0);
assert.ok(steps.every((s) => isVisitNodeStep(s)));

assert.strictEqual(steps[0].target.type, 'Program');
assert.strictEqual(steps[0].phase, 1);
assert.strictEqual(steps[steps.length - 1].target.type, 'Program');
assert.strictEqual(steps[steps.length - 1].phase, 2);

const enters = steps.filter((s) => s.phase === 1);
const exits = steps.filter((s) => s.phase === 2);
assert.strictEqual(enters.length, exits.length);

console.log('All VisitNodeStep contract assertions passed successfully.');