estraverse 5.3.0: VisitorOption

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.VisitorOption 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.VisitorOption
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:860c369d861c58e73069593fb604d033dc5878a2028151261451484d5a9236da","constraints":{"executionContext":"node"},"contract":["estraverse.VisitorOption provides Skip, Break, and Remove constants","estraverse.VisitorOption.Skip skips child traversal in estraverse.traverse","estraverse.VisitorOption.Break halts traversal immediately in estraverse.traverse","estraverse.VisitorOption.Remove deletes the current node in estraverse.replace"],"goal":"verify estraverse.VisitorOption in pkg:npm/estraverse@5.3.0","kind":"HOW","packages":["pkg:npm/estraverse@5.3.0"],"schemaVersion":1,"symbols":["estraverse.VisitorOption"]},"contractCommand":["node","test/contract.js"],"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.VisitorOption"],"verifierAdapter":"node-typescript@1"}

const estraverse = require('estraverse');

/**
 * Traverses an AST with optional skipping of subtree nodes.
 * @param {object} ast
 * @param {Function} shouldSkipNode - predicate returning true if children should be skipped
 * @returns {Array<object>} visited nodes
 */
function traverseWithSkip(ast, shouldSkipNode) {
  const visited = [];
  estraverse.traverse(ast, {
    enter(node) {
      visited.push(node);
      if (shouldSkipNode && shouldSkipNode(node)) {
        return estraverse.VisitorOption.Skip;
      }
    }
  });
  return visited;
}

/**
 * Finds the first node matching a predicate, stopping traversal immediately.
 * @param {object} ast
 * @param {Function} predicate
 * @returns {object|null}
 */
function findFirstWithBreak(ast, predicate) {
  let found = null;
  estraverse.traverse(ast, {
    enter(node) {
      if (predicate(node)) {
        found = node;
        return estraverse.VisitorOption.Break;
      }
    }
  });
  return found;
}

/**
 * Removes nodes matching a predicate from an AST.
 * @param {object} ast
 * @param {Function} predicate
 * @returns {object} modified AST
 */
function removeMatchingNodes(ast, predicate) {
  return estraverse.replace(ast, {
    enter(node) {
      if (predicate(node)) {
        return estraverse.VisitorOption.Remove;
      }
    }
  });
}

module.exports = {
  VisitorOption: estraverse.VisitorOption,
  traverseWithSkip,
  findFirstWithBreak,
  removeMatchingNodes
};

{
  "name": "sample-estraverse-visitor-option",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-estraverse-visitor-option",
      "version": "1.0.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-option",
  "version": "1.0.0",
  "private": true,
  "description": "Sample verifying estraverse.VisitorOption",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "estraverse": "5.3.0"
  }
}

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

const assert = require('assert');
const estraverse = require('estraverse');
const {
  VisitorOption,
  traverseWithSkip,
  findFirstWithBreak,
  removeMatchingNodes
} = require('../index.js');

// 1. Verify VisitorOption constants exist
assert.ok(estraverse.VisitorOption, 'estraverse.VisitorOption must be defined');
assert.ok(estraverse.VisitorOption.Skip, 'VisitorOption.Skip must be defined');
assert.ok(estraverse.VisitorOption.Break, 'VisitorOption.Break must be defined');
assert.ok(estraverse.VisitorOption.Remove, 'VisitorOption.Remove must be defined');
assert.strictEqual(VisitorOption, estraverse.VisitorOption);

const sampleAst = {
  type: 'Program',
  body: [
    {
      type: 'FunctionDeclaration',
      id: { type: 'Identifier', name: 'targetFunc' },
      body: {
        type: 'BlockStatement',
        body: [
          {
            type: 'ExpressionStatement',
            expression: { type: 'Literal', value: 'inside-target' }
          }
        ]
      }
    },
    {
      type: 'FunctionDeclaration',
      id: { type: 'Identifier', name: 'otherFunc' },
      body: {
        type: 'BlockStatement',
        body: [
          {
            type: 'ExpressionStatement',
            expression: { type: 'Literal', value: 'keep-me' }
          },
          {
            type: 'ExpressionStatement',
            expression: { type: 'Literal', value: 'remove-me' }
          }
        ]
      }
    }
  ]
};

// 2. Verify VisitorOption.Skip skips child nodes
{
  const visited = traverseWithSkip(sampleAst, (node) => {
    return node.type === 'FunctionDeclaration' && node.id && node.id.name === 'targetFunc';
  });
  const visitedTypes = visited.map((n) => n.type);
  assert.ok(visitedTypes.includes('FunctionDeclaration'));
  const insideTargetLiterals = visited.filter(
    (n) => n.type === 'Literal' && n.value === 'inside-target'
  );
  assert.strictEqual(insideTargetLiterals.length, 0, 'Children of skipped node should not be visited');
}

// 3. Verify VisitorOption.Break halts traversal immediately
{
  const firstFunc = findFirstWithBreak(sampleAst, (node) => node.type === 'FunctionDeclaration');
  assert.ok(firstFunc);
  assert.strictEqual(firstFunc.id.name, 'targetFunc');
}

// 4. Verify VisitorOption.Remove removes matched nodes during replace
{
  const astCopy = JSON.parse(JSON.stringify(sampleAst));
  const modified = removeMatchingNodes(astCopy, (node) => {
    return (
      node.type === 'ExpressionStatement' &&
      node.expression &&
      node.expression.value === 'remove-me'
    );
  });
  const otherFuncBody = modified.body[1].body.body;
  assert.strictEqual(otherFuncBody.length, 1);
  assert.strictEqual(otherFuncBody[0].expression.value, 'keep-me');
}

console.log('All contract assertions for estraverse.VisitorOption passed.');