estraverse 5.3.0: VisitorKeys

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 estraverse.VisitorKeys in pkg:npm/estraverse@5.3.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/estraverse@5.3.0
Demonstrate these symbols/APIs:
  - estraverse.VisitorKeys
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:3d227ea594b3a6224ba43b0c7f398373cf1a0c90c57a77eb28572762a73898c4","constraints":{"executionContext":"node"},"contract":["estraverse.VisitorKeys is exported as an object mapping AST node type names to arrays of child visitor key strings","VisitorKeys defines child property keys for ESTree statements and declarations including Program, FunctionDeclaration, and VariableDeclaration","VisitorKeys defines child property keys for ESTree expressions and clauses including BinaryExpression, CallExpression, MemberExpression, and CatchClause","VisitorKeys defines empty child arrays for ESTree leaf nodes including Identifier, Literal, and ThisExpression","VisitorKeys defines child property keys for ES6+ AST node types including ArrowFunctionExpression, ClassDeclaration, TemplateLiteral, and YieldExpression","VisitorKeys allows custom AST node traversal and child extraction with estraverse.traverse and VisitorKeys mapping"],"goal":"verify estraverse.VisitorKeys in pkg:npm/estraverse@5.3.0","kind":"HOW","packages":["pkg:npm/estraverse@5.3.0"],"schemaVersion":1,"symbols":["estraverse.VisitorKeys"]},"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/estraverse@5.3.0"],"schemaVersion":1,"subject":"pkg:npm/estraverse@5.3.0","symbols":["estraverse.VisitorKeys"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-estraverse-visitor-keys",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-estraverse-visitor-keys",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "estraverse": "5.3.0"
      }
    },
    "node_modules/estraverse": {
      "version": "5.3.0",
      "resolved": "https://registry.npmjs.org/estraverse/-/estraverse-5.3.0.tgz",
      "integrity": "sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==",
      "license": "BSD-2-Clause",
      "engines": {
        "node": ">=4.0"
      }
    }
  }
}

{
  "name": "sample-estraverse-visitor-keys",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for estraverse.VisitorKeys in estraverse@5.3.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "estraverse": "5.3.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify estraverse.VisitorKeys in pkg:npm/estraverse@5.3.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/estraverse@5.3.0"
  ],
  "symbols": [
    "estraverse.VisitorKeys"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const estraverse = require('estraverse');

const { VisitorKeys, Syntax, traverse, replace } = estraverse;

/**
 * Returns the child visitor keys for a given ESTree AST node type.
 *
 * @param {string} nodeType - The AST node type string (e.g. 'BinaryExpression').
 * @param {Object} [customKeys] - Optional custom visitor keys dictionary.
 * @returns {string[]} Array of child key property names.
 */
function getChildKeys(nodeType, customKeys) {
  const keys = (customKeys && customKeys[nodeType]) || VisitorKeys[nodeType];
  return keys ? [...keys] : [];
}

/**
 * Checks whether a given AST node type is a leaf node (i.e. has no child nodes).
 *
 * @param {string} nodeType - The AST node type string (e.g. 'Identifier', 'Literal').
 * @param {Object} [customKeys] - Optional custom visitor keys dictionary.
 * @returns {boolean} True if the node type is a registered leaf node.
 */
function isLeafNode(nodeType, customKeys) {
  const keys = (customKeys && customKeys[nodeType]) || VisitorKeys[nodeType];
  return Array.isArray(keys) && keys.length === 0;
}

/**
 * Extracts immediate child AST nodes from a given AST node based on VisitorKeys.
 *
 * @param {Object} node - The AST node to inspect.
 * @param {Object} [customKeys] - Optional custom visitor keys dictionary.
 * @returns {Object[]} Array of immediate child AST node objects.
 */
function extractChildNodes(node, customKeys) {
  if (!node || typeof node !== 'object' || typeof node.type !== 'string') {
    return [];
  }
  const childKeys = getChildKeys(node.type, customKeys);
  const children = [];

  for (const key of childKeys) {
    const value = node[key];
    if (Array.isArray(value)) {
      for (const item of value) {
        if (item && typeof item === 'object' && typeof item.type === 'string') {
          children.push(item);
        }
      }
    } else if (value && typeof value === 'object' && typeof value.type === 'string') {
      children.push(value);
    }
  }

  return children;
}

/**
 * Traverses an AST with custom node support by merging user keys with VisitorKeys.
 *
 * @param {Object} ast - The root AST node.
 * @param {Object} visitor - Visitor object with enter/leave hooks.
 * @param {Object} [extensionKeys] - Additional node type visitor keys.
 */
function traverseWithCustomKeys(ast, visitor, extensionKeys = {}) {
  const mergedKeys = {
    ...VisitorKeys,
    ...extensionKeys
  };
  return traverse(ast, {
    ...visitor,
    keys: mergedKeys
  });
}

/**
 * Collects all child property names defined across all AST node types in VisitorKeys.
 *
 * @returns {string[]} Sorted array of unique child property names.
 */
function getAllChildPropertyNames() {
  const propertySet = new Set();
  for (const keys of Object.values(VisitorKeys)) {
    for (const key of keys) {
      propertySet.add(key);
    }
  }
  return Array.from(propertySet).sort();
}

module.exports = {
  estraverse,
  VisitorKeys,
  Syntax,
  traverse,
  replace,
  getChildKeys,
  isLeafNode,
  extractChildNodes,
  traverseWithCustomKeys,
  getAllChildPropertyNames
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  estraverse,
  VisitorKeys,
  Syntax,
  traverse,
  getChildKeys,
  isLeafNode,
  extractChildNodes,
  traverseWithCustomKeys,
  getAllChildPropertyNames
} = require('../src/index.js');

async function runTests() {
  // 1. estraverse.VisitorKeys is exported as an object mapping AST node type names to arrays of child visitor key strings
  assert.equal(typeof VisitorKeys, 'object', 'VisitorKeys must be exported as an object');
  assert.ok(VisitorKeys !== null, 'VisitorKeys must not be null');
  assert.strictEqual(estraverse.VisitorKeys, VisitorKeys, 'estraverse.VisitorKeys must match exported VisitorKeys');

  const nodeTypes = Object.keys(VisitorKeys);
  assert.ok(nodeTypes.length > 50, 'VisitorKeys should define visitor keys for standard ESTree node types');
  for (const nodeType of nodeTypes) {
    assert.equal(typeof nodeType, 'string', 'Node type key must be a string');
    assert.ok(Array.isArray(VisitorKeys[nodeType]), `VisitorKeys[${nodeType}] must be an array`);
    for (const key of VisitorKeys[nodeType]) {
      assert.equal(typeof key, 'string', `VisitorKeys[${nodeType}] child key must be a string`);
    }
  }

  // 2. VisitorKeys defines child property keys for ESTree statements and declarations including Program, FunctionDeclaration, and VariableDeclaration
  assert.deepStrictEqual(VisitorKeys.Program, ['body']);
  assert.deepStrictEqual(VisitorKeys.FunctionDeclaration, ['id', 'params', 'body']);
  assert.deepStrictEqual(VisitorKeys.FunctionExpression, ['id', 'params', 'body']);
  assert.deepStrictEqual(VisitorKeys.VariableDeclaration, ['declarations']);
  assert.deepStrictEqual(VisitorKeys.VariableDeclarator, ['id', 'init']);
  assert.deepStrictEqual(VisitorKeys.BlockStatement, ['body']);
  assert.deepStrictEqual(VisitorKeys.IfStatement, ['test', 'consequent', 'alternate']);
  assert.deepStrictEqual(VisitorKeys.ForStatement, ['init', 'test', 'update', 'body']);
  assert.deepStrictEqual(VisitorKeys.ForInStatement, ['left', 'right', 'body']);
  assert.deepStrictEqual(VisitorKeys.ForOfStatement, ['left', 'right', 'body']);
  assert.deepStrictEqual(VisitorKeys.WhileStatement, ['test', 'body']);
  assert.deepStrictEqual(VisitorKeys.DoWhileStatement, ['body', 'test']);
  assert.deepStrictEqual(VisitorKeys.ReturnStatement, ['argument']);
  assert.deepStrictEqual(VisitorKeys.ThrowStatement, ['argument']);
  assert.deepStrictEqual(VisitorKeys.TryStatement, ['block', 'handler', 'finalizer']);
  assert.deepStrictEqual(VisitorKeys.ExpressionStatement, ['expression']);
  assert.deepStrictEqual(VisitorKeys.LabeledStatement, ['label', 'body']);

  // Verify getChildKeys helper for statements
  assert.deepStrictEqual(getChildKeys('Program'), ['body']);
  assert.deepStrictEqual(getChildKeys('FunctionDeclaration'), ['id', 'params', 'body']);
  assert.deepStrictEqual(getChildKeys('VariableDeclaration'), ['declarations']);

  // 3. VisitorKeys defines child property keys for ESTree expressions and clauses including BinaryExpression, CallExpression, MemberExpression, and CatchClause
  assert.deepStrictEqual(VisitorKeys.BinaryExpression, ['left', 'right']);
  assert.deepStrictEqual(VisitorKeys.LogicalExpression, ['left', 'right']);
  assert.deepStrictEqual(VisitorKeys.AssignmentExpression, ['left', 'right']);
  assert.deepStrictEqual(VisitorKeys.CallExpression, ['callee', 'arguments']);
  assert.deepStrictEqual(VisitorKeys.MemberExpression, ['object', 'property']);
  assert.deepStrictEqual(VisitorKeys.UnaryExpression, ['argument']);
  assert.deepStrictEqual(VisitorKeys.UpdateExpression, ['argument']);
  assert.deepStrictEqual(VisitorKeys.ArrayExpression, ['elements']);
  assert.deepStrictEqual(VisitorKeys.ObjectExpression, ['properties']);
  assert.deepStrictEqual(VisitorKeys.Property, ['key', 'value']);
  assert.deepStrictEqual(VisitorKeys.CatchClause, ['param', 'body']);
  assert.deepStrictEqual(VisitorKeys.SwitchStatement, ['discriminant', 'cases']);
  assert.deepStrictEqual(VisitorKeys.SwitchCase, ['test', 'consequent']);
  assert.deepStrictEqual(VisitorKeys.ConditionalExpression, ['test', 'consequent', 'alternate']);
  assert.deepStrictEqual(VisitorKeys.NewExpression, ['callee', 'arguments']);

  // 4. VisitorKeys defines empty child arrays for ESTree leaf nodes including Identifier, Literal, and ThisExpression
  assert.deepStrictEqual(VisitorKeys.Identifier, []);
  assert.deepStrictEqual(VisitorKeys.Literal, []);
  assert.deepStrictEqual(VisitorKeys.ThisExpression, []);
  assert.deepStrictEqual(VisitorKeys.EmptyStatement, []);
  assert.deepStrictEqual(VisitorKeys.DebuggerStatement, []);
  assert.deepStrictEqual(VisitorKeys.Super, []);
  assert.deepStrictEqual(VisitorKeys.PrivateIdentifier, []);

  assert.strictEqual(isLeafNode('Identifier'), true);
  assert.strictEqual(isLeafNode('Literal'), true);
  assert.strictEqual(isLeafNode('ThisExpression'), true);
  assert.strictEqual(isLeafNode('BinaryExpression'), false);
  assert.strictEqual(isLeafNode('Program'), false);

  // 5. VisitorKeys defines child property keys for ES6+ AST node types including ArrowFunctionExpression, ClassDeclaration, TemplateLiteral, and YieldExpression
  assert.deepStrictEqual(VisitorKeys.ArrowFunctionExpression, ['params', 'body']);
  assert.deepStrictEqual(VisitorKeys.ClassDeclaration, ['id', 'superClass', 'body']);
  assert.deepStrictEqual(VisitorKeys.ClassExpression, ['id', 'superClass', 'body']);
  assert.deepStrictEqual(VisitorKeys.ClassBody, ['body']);
  assert.deepStrictEqual(VisitorKeys.MethodDefinition, ['key', 'value']);
  assert.deepStrictEqual(VisitorKeys.PropertyDefinition, ['key', 'value']);
  assert.deepStrictEqual(VisitorKeys.TemplateLiteral, ['quasis', 'expressions']);
  assert.deepStrictEqual(VisitorKeys.TaggedTemplateExpression, ['tag', 'quasi']);
  assert.deepStrictEqual(VisitorKeys.SpreadElement, ['argument']);
  assert.deepStrictEqual(VisitorKeys.RestElement, ['argument']);
  assert.deepStrictEqual(VisitorKeys.AwaitExpression, ['argument']);
  assert.deepStrictEqual(VisitorKeys.YieldExpression, ['argument']);
  assert.deepStrictEqual(VisitorKeys.ImportDeclaration, ['specifiers', 'source']);
  assert.deepStrictEqual(VisitorKeys.ExportNamedDeclaration, ['declaration', 'specifiers', 'source']);
  assert.deepStrictEqual(VisitorKeys.ExportDefaultDeclaration, ['declaration']);
  assert.deepStrictEqual(VisitorKeys.ChainExpression, ['expression']);
  assert.deepStrictEqual(VisitorKeys.ImportExpression, ['source']);

  // 6. VisitorKeys allows custom AST node traversal and child extraction with estraverse.traverse and VisitorKeys mapping
  const sampleAst = {
    type: 'Program',
    body: [
      {
        type: 'VariableDeclaration',
        kind: 'const',
        declarations: [
          {
            type: 'VariableDeclarator',
            id: { type: 'Identifier', name: 'total' },
            init: {
              type: 'BinaryExpression',
              operator: '+',
              left: { type: 'Identifier', name: 'a' },
              right: { type: 'Literal', value: 10 }
            }
          }
        ]
      },
      {
        type: 'CustomPipeExpression',
        input: { type: 'Identifier', name: 'sourceStream' },
        transform: { type: 'Identifier', name: 'filterStream' }
      }
    ]
  };

  // Test extractChildNodes on standard nodes
  const programChildren = extractChildNodes(sampleAst);
  assert.strictEqual(programChildren.length, 2);
  assert.strictEqual(programChildren[0].type, 'VariableDeclaration');
  assert.strictEqual(programChildren[1].type, 'CustomPipeExpression');

  const varDeclChildren = extractChildNodes(sampleAst.body[0]);
  assert.strictEqual(varDeclChildren.length, 1);
  assert.strictEqual(varDeclChildren[0].type, 'VariableDeclarator');

  const varDeclaratorChildren = extractChildNodes(varDeclChildren[0]);
  assert.strictEqual(varDeclaratorChildren.length, 2);
  assert.strictEqual(varDeclaratorChildren[0].name, 'total');
  assert.strictEqual(varDeclaratorChildren[1].type, 'BinaryExpression');

  // Test extractChildNodes on custom node with customKeys
  const customPipeChildren = extractChildNodes(sampleAst.body[1], {
    CustomPipeExpression: ['input', 'transform']
  });
  assert.strictEqual(customPipeChildren.length, 2);
  assert.strictEqual(customPipeChildren[0].name, 'sourceStream');
  assert.strictEqual(customPipeChildren[1].name, 'filterStream');

  // Test traverseWithCustomKeys
  const visitedTypes = [];
  traverseWithCustomKeys(
    sampleAst,
    {
      enter(node) {
        visitedTypes.push(node.type);
      }
    },
    {
      CustomPipeExpression: ['input', 'transform']
    }
  );

  assert.deepStrictEqual(visitedTypes, [
    'Program',
    'VariableDeclaration',
    'VariableDeclarator',
    'Identifier',
    'BinaryExpression',
    'Identifier',
    'Literal',
    'CustomPipeExpression',
    'Identifier',
    'Identifier'
  ]);

  const allPropNames = getAllChildPropertyNames();
  assert.ok(allPropNames.includes('body'));
  assert.ok(allPropNames.includes('left'));
  assert.ok(allPropNames.includes('right'));
  assert.ok(allPropNames.includes('callee'));
  assert.ok(allPropNames.includes('arguments'));

  console.log('All contract assertions for estraverse.VisitorKeys passed successfully.');
}

runTests().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});