estraverse 5.3.0: Controller

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.Controller 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.Controller

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:3ff9781675fdac5ea5334138167a5f1e352648b9de10c9220849537bb507f1a9","contract":["estraverse.Controller is exported as a constructor function from estraverse","Controller instance traverses AST nodes in depth-first order invoking enter and leave callbacks","Controller provides current(), type(), path(), and parents() accessors during traversal","Controller.prototype.skip bypasses traversal of descendant nodes","Controller.prototype.break terminates AST traversal immediately","Controller.prototype.replace transforms matching AST nodes and supports Controller.prototype.remove to delete nodes"],"goal":"verify estraverse.Controller in pkg:npm/estraverse@5.3.0","kind":"HOW","packages":["pkg:npm/estraverse@5.3.0"],"schemaVersion":1,"symbols":["estraverse.Controller"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/estraverse@5.3.0"],"schemaVersion":1,"subject":"pkg:npm/estraverse@5.3.0","symbols":["estraverse.Controller"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-estraverse-controller",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-estraverse-controller",
      "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-controller",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for estraverse.Controller in estraverse@5.3.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "estraverse": "5.3.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify estraverse.Controller in pkg:npm/estraverse@5.3.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/estraverse@5.3.0"
  ],
  "symbols": [
    "estraverse.Controller"
  ]
}

const estraverse = require('estraverse');

const {
  Controller,
  VisitorOption,
  Syntax,
  VisitorKeys
} = estraverse;

/**
 * Creates a new estraverse Controller instance.
 *
 * @returns {estraverse.Controller}
 */
function createController() {
  return new Controller();
}

/**
 * Traverses an AST tree using Controller and visits each node.
 *
 * @param {object} ast - AST node to traverse.
 * @param {object} visitor - Visitor object with enter/leave callbacks.
 * @returns {estraverse.Controller} The controller used for traversal.
 */
function traverseAst(ast, visitor) {
  const controller = new Controller();
  controller.traverse(ast, visitor);
  return controller;
}

/**
 * Traverses and replaces AST nodes using Controller.
 *
 * @param {object} ast - AST node to transform.
 * @param {object} visitor - Visitor object with enter/leave callbacks returning replacement nodes or using remove().
 * @returns {object} Transformed AST root node.
 */
function replaceAst(ast, visitor) {
  const controller = new Controller();
  return controller.replace(ast, visitor);
}

/**
 * Collects all node types visited in depth-first order.
 *
 * @param {object} ast - AST root node.
 * @returns {string[]} Array of node type strings.
 */
function collectNodeTypes(ast) {
  const types = [];
  const controller = new Controller();
  controller.traverse(ast, {
    enter(node) {
      types.push(node.type);
    }
  });
  return types;
}

module.exports = {
  estraverse,
  Controller,
  VisitorOption,
  Syntax,
  VisitorKeys,
  createController,
  traverseAst,
  replaceAst,
  collectNodeTypes
};

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

const require = createRequire(import.meta.url);
const {
  estraverse,
  Controller,
  VisitorOption,
  Syntax,
  createController,
  traverseAst,
  replaceAst,
  collectNodeTypes
} = require('../src/index.js');

async function runTests() {
  // 1. estraverse.Controller is exported as a constructor function from estraverse
  assert.equal(typeof Controller, 'function', 'Controller must be exported as a function/constructor');
  assert.equal(typeof estraverse.Controller, 'function', 'estraverse.Controller must be a constructor function');
  const inst = createController();
  assert.ok(inst instanceof Controller, 'createController must return an instance of Controller');
  assert.equal(typeof inst.traverse, 'function', 'Controller.prototype.traverse must be a function');
  assert.equal(typeof inst.replace, 'function', 'Controller.prototype.replace must be a function');
  assert.equal(typeof inst.skip, 'function', 'Controller.prototype.skip must be a function');
  assert.equal(typeof inst.break, 'function', 'Controller.prototype.break must be a function');
  assert.equal(typeof inst.remove, 'function', 'Controller.prototype.remove must be a function');

  // 2. Controller instance traverses AST nodes in depth-first order invoking enter and leave callbacks
  const sampleAst = {
    type: 'Program',
    body: [
      {
        type: 'ExpressionStatement',
        expression: {
          type: 'BinaryExpression',
          operator: '+',
          left: { type: 'Identifier', name: 'a' },
          right: { type: 'Literal', value: 10 }
        }
      }
    ]
  };

  const entered = [];
  const left = [];
  const controller = new Controller();

  controller.traverse(sampleAst, {
    enter(node) {
      entered.push(node.type);
    },
    leave(node) {
      left.push(node.type);
    }
  });

  assert.deepEqual(entered, [
    'Program',
    'ExpressionStatement',
    'BinaryExpression',
    'Identifier',
    'Literal'
  ], 'enter callback must visit nodes in depth-first preorder');

  assert.deepEqual(left, [
    'Identifier',
    'Literal',
    'BinaryExpression',
    'ExpressionStatement',
    'Program'
  ], 'leave callback must visit nodes in depth-first postorder');

  // 3. Controller provides current(), type(), path(), and parents() accessors during traversal
  const astWithHierarchy = {
    type: 'Program',
    body: [
      {
        type: 'VariableDeclaration',
        kind: 'const',
        declarations: [
          {
            type: 'VariableDeclarator',
            id: { type: 'Identifier', name: 'total' },
            init: { type: 'Literal', value: 100 }
          }
        ]
      }
    ]
  };

  let identifierVerified = false;
  const hierarchyController = new Controller();

  hierarchyController.traverse(astWithHierarchy, {
    enter(node) {
      assert.strictEqual(hierarchyController.current(), node, 'current() must return the currently traversed node');
      assert.strictEqual(hierarchyController.type(), node.type, 'type() must match node.type');

      if (node.type === 'Identifier' && node.name === 'total') {
        identifierVerified = true;
        const parents = hierarchyController.parents();
        assert.equal(parents.length, 3, 'Identifier node should have 3 ancestors: Program, VariableDeclaration, VariableDeclarator');
        assert.equal(parents[0].type, 'Program');
        assert.equal(parents[1].type, 'VariableDeclaration');
        assert.equal(parents[2].type, 'VariableDeclarator');

        const currentPath = hierarchyController.path();
        assert.deepEqual(currentPath, ['body', 0, 'declarations', 0, 'id'], 'path() must return array of property keys and indices leading to node');
      }
    }
  });
  assert.ok(identifierVerified, 'Identifier hierarchy inspection must execute');

  // 4. Controller.prototype.skip bypasses traversal of descendant nodes
  const skipAst = {
    type: 'Program',
    body: [
      {
        type: 'BlockStatement',
        body: [
          { type: 'Identifier', name: 'skippedChild1' },
          { type: 'Identifier', name: 'skippedChild2' }
        ]
      },
      {
        type: 'ExpressionStatement',
        expression: { type: 'Identifier', name: 'visitedSibling' }
      }
    ]
  };

  const visitedTypes = [];
  const skipController = new Controller();
  skipController.traverse(skipAst, {
    enter(node) {
      visitedTypes.push(node.type);
      if (node.type === 'BlockStatement') {
        skipController.skip();
      }
    }
  });

  assert.deepEqual(visitedTypes, [
    'Program',
    'BlockStatement',
    'ExpressionStatement',
    'Identifier'
  ], 'skip() must skip child nodes of BlockStatement but continue with sibling ExpressionStatement');

  // 5. Controller.prototype.break terminates AST traversal immediately
  const breakAst = {
    type: 'Program',
    body: [
      { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'first' } },
      { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'second' } },
      { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'third' } }
    ]
  };

  const breakVisitedNames = [];
  const breakController = new Controller();
  breakController.traverse(breakAst, {
    enter(node) {
      if (node.type === 'Identifier') {
        breakVisitedNames.push(node.name);
        if (node.name === 'second') {
          breakController.break();
        }
      }
    }
  });

  assert.deepEqual(breakVisitedNames, ['first', 'second'], 'break() must immediately halt further traversal');

  // 6. Controller.prototype.replace transforms matching AST nodes and supports Controller.prototype.remove to delete nodes
  const transformAst = {
    type: 'Program',
    body: [
      {
        type: 'ExpressionStatement',
        expression: { type: 'Identifier', name: 'oldName' }
      },
      {
        type: 'ExpressionStatement',
        expression: { type: 'Identifier', name: 'toBeRemoved' }
      },
      {
        type: 'ExpressionStatement',
        expression: { type: 'Identifier', name: 'keep' }
      }
    ]
  };

  const transformController = new Controller();
  const transformed = transformController.replace(transformAst, {
    enter(node) {
      if (node.type === 'Identifier' && node.name === 'oldName') {
        return { type: 'Identifier', name: 'newName' };
      }
      if (node.type === 'ExpressionStatement' && node.expression.name === 'toBeRemoved') {
        this.remove();
      }
    }
  });

  assert.equal(transformed.body.length, 2, 'replace with this.remove() must remove the target node');
  assert.equal(transformed.body[0].expression.name, 'newName', 'replace must update the modified node');
  assert.equal(transformed.body[1].expression.name, 'keep', 'replace must preserve unmodified nodes');

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

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