ast-types 0.13.4: AST traversal and transformation with visit and namedTypes check

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: AST traversal and transformation with visit and namedTypes check
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ast-types@0.13.4
Demonstrate these symbols/APIs:
  - ast-types.builders
  - ast-types.namedTypes
  - ast-types.visit

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:b8a904bfb4bbbe6628a01d8d8a7363aec2f1c1ded9ff428bdf08e8f4c32fff17","contract":["builders constructs AST nodes including identifier, literal, and binaryExpression","builders constructs declarations and statements including variableDeclaration and functionDeclaration","namedTypes provides type predicate checks such as Identifier.check and Expression.check","namedTypes provides type assertions such as Identifier.assert and Expression.assert that throw on type mismatch","visit traverses an AST and supports node replacement via visitor methods"],"goal":"AST traversal and transformation with visit and namedTypes check","kind":"HOW","packages":["pkg:npm/ast-types@0.13.4"],"schemaVersion":1,"symbols":["ast-types.builders","ast-types.namedTypes","ast-types.visit"]},"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/ast-types@0.13.4"],"schemaVersion":1,"subject":"pkg:npm/ast-types@0.13.4","symbols":["ast-types.builders","ast-types.namedTypes","ast-types.visit"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-ast-types",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-ast-types",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "ast-types": "0.13.4"
      }
    },
    "node_modules/ast-types": {
      "version": "0.13.4",
      "resolved": "https://registry.npmjs.org/ast-types/-/ast-types-0.13.4.tgz",
      "integrity": "sha512-x1FCFnFifvYDDzTaLII71vG5uvDwgtmDTEVWAxrgeiR8VjMONcCXJx7E+USjDtHlwFmt9MysbqgF9b9Vjr6w+w==",
      "license": "MIT",
      "dependencies": {
        "tslib": "^2.0.1"
      },
      "engines": {
        "node": ">=4"
      }
    },
    "node_modules/tslib": {
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
      "license": "0BSD"
    }
  }
}

{
  "name": "sample-ast-types",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of ast-types",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "ast-types": "0.13.4"
  }
}

{
  "schemaVersion": 1,
  "goal": "AST traversal and transformation with visit and namedTypes check",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ast-types@0.13.4"
  ],
  "symbols": [
    "ast-types.builders",
    "ast-types.namedTypes",
    "ast-types.visit"
  ]
}

const { builders, namedTypes, visit } = require('ast-types');

/**
 * Creates an Identifier AST node.
 * @param {string} name
 * @returns {object}
 */
function createIdentifier(name) {
  return builders.identifier(name);
}

/**
 * Creates a Literal AST node.
 * @param {string|number|boolean|null} value
 * @returns {object}
 */
function createLiteral(value) {
  return builders.literal(value);
}

/**
 * Creates a BinaryExpression AST node.
 * @param {string} operator
 * @param {object} left
 * @param {object} right
 * @returns {object}
 */
function createBinaryExpression(operator, left, right) {
  return builders.binaryExpression(operator, left, right);
}

/**
 * Creates a VariableDeclaration AST node.
 * @param {string} kind
 * @param {string|object} id
 * @param {object} init
 * @returns {object}
 */
function createVariableDeclaration(kind, id, init) {
  const idNode = typeof id === 'string' ? builders.identifier(id) : id;
  const declarator = builders.variableDeclarator(idNode, init);
  return builders.variableDeclaration(kind, [declarator]);
}

/**
 * Creates a FunctionDeclaration AST node.
 * @param {string|object} id
 * @param {Array<object>} params
 * @param {Array<object>} bodyStatements
 * @returns {object}
 */
function createFunctionDeclaration(id, params, bodyStatements) {
  const idNode = typeof id === 'string' ? builders.identifier(id) : id;
  const block = builders.blockStatement(bodyStatements);
  return builders.functionDeclaration(idNode, params, block);
}

/**
 * Renames all identifiers in an AST matching oldName to newName.
 * @param {object} ast
 * @param {string} oldName
 * @param {string} newName
 * @returns {object}
 */
function renameIdentifiers(ast, oldName, newName) {
  visit(ast, {
    visitIdentifier(path) {
      if (path.node.name === oldName) {
        path.replace(builders.identifier(newName));
      }
      this.traverse(path);
    },
  });
  return ast;
}

module.exports = {
  builders,
  namedTypes,
  visit,
  createIdentifier,
  createLiteral,
  createBinaryExpression,
  createVariableDeclaration,
  createFunctionDeclaration,
  renameIdentifiers,
};

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

const require = createRequire(import.meta.url);
const {
  builders,
  namedTypes,
  visit,
  createIdentifier,
  createLiteral,
  createBinaryExpression,
  createVariableDeclaration,
  createFunctionDeclaration,
  renameIdentifiers,
} = require('../src/index.js');

async function runContract() {
  // 1. builders constructs AST nodes including identifier, literal, and binaryExpression
  const idNode = createIdentifier('count');
  assert.strictEqual(idNode.type, 'Identifier');
  assert.strictEqual(idNode.name, 'count');

  const numLit = createLiteral(42);
  assert.strictEqual(numLit.type, 'Literal');
  assert.strictEqual(numLit.value, 42);

  const strLit = createLiteral('hello');
  assert.strictEqual(strLit.type, 'Literal');
  assert.strictEqual(strLit.value, 'hello');

  const binExpr = createBinaryExpression('+', idNode, numLit);
  assert.strictEqual(binExpr.type, 'BinaryExpression');
  assert.strictEqual(binExpr.operator, '+');
  assert.strictEqual(binExpr.left, idNode);
  assert.strictEqual(binExpr.right, numLit);

  // 2. builders constructs declarations and statements including variableDeclaration and functionDeclaration
  const varDecl = createVariableDeclaration('const', 'result', binExpr);
  assert.strictEqual(varDecl.type, 'VariableDeclaration');
  assert.strictEqual(varDecl.kind, 'const');
  assert.strictEqual(varDecl.declarations.length, 1);
  assert.strictEqual(varDecl.declarations[0].type, 'VariableDeclarator');
  assert.strictEqual(varDecl.declarations[0].id.name, 'result');
  assert.strictEqual(varDecl.declarations[0].init, binExpr);

  const retStmt = builders.returnStatement(binExpr);
  assert.strictEqual(retStmt.type, 'ReturnStatement');
  assert.strictEqual(retStmt.argument, binExpr);

  const fnDecl = createFunctionDeclaration('calculate', [idNode], [retStmt]);
  assert.strictEqual(fnDecl.type, 'FunctionDeclaration');
  assert.strictEqual(fnDecl.id.name, 'calculate');
  assert.strictEqual(fnDecl.params.length, 1);
  assert.strictEqual(fnDecl.body.type, 'BlockStatement');
  assert.strictEqual(fnDecl.body.body[0], retStmt);

  // 3. namedTypes provides type predicate checks such as Identifier.check and Expression.check
  assert.strictEqual(namedTypes.Identifier.check(idNode), true);
  assert.strictEqual(namedTypes.Identifier.check(numLit), false);
  assert.strictEqual(namedTypes.Literal.check(numLit), true);
  assert.strictEqual(namedTypes.Literal.check(strLit), true);
  assert.strictEqual(namedTypes.BinaryExpression.check(binExpr), true);
  assert.strictEqual(namedTypes.Expression.check(binExpr), true);
  assert.strictEqual(namedTypes.Expression.check(idNode), true);
  assert.strictEqual(namedTypes.Statement.check(varDecl), true);
  assert.strictEqual(namedTypes.Statement.check(fnDecl), true);
  assert.strictEqual(namedTypes.Statement.check(binExpr), false);

  // 4. namedTypes provides type assertions such as Identifier.assert and Expression.assert that throw on type mismatch
  namedTypes.Identifier.assert(idNode);
  namedTypes.Literal.assert(numLit);
  namedTypes.BinaryExpression.assert(binExpr);
  namedTypes.Expression.assert(binExpr);
  namedTypes.Statement.assert(varDecl);

  assert.throws(
    () => namedTypes.Identifier.assert(numLit),
    (err) => err instanceof Error,
    'Identifier.assert must throw on non-identifier node'
  );
  assert.throws(
    () => namedTypes.Literal.assert(idNode),
    (err) => err instanceof Error,
    'Literal.assert must throw on non-literal node'
  );
  assert.throws(
    () => namedTypes.Statement.assert(binExpr),
    (err) => err instanceof Error,
    'Statement.assert must throw on expression node'
  );

  // 5. visit traverses an AST and supports node replacement via visitor methods
  const ast = builders.program([
    builders.variableDeclaration('var', [
      builders.variableDeclarator(builders.identifier('oldVar'), builders.literal('value')),
    ]),
    builders.expressionStatement(
      builders.callExpression(builders.identifier('logger'), [builders.identifier('oldVar')])
    ),
  ]);

  renameIdentifiers(ast, 'oldVar', 'newVar');

  assert.strictEqual(ast.body[0].declarations[0].id.name, 'newVar');
  assert.strictEqual(ast.body[1].expression.arguments[0].name, 'newVar');

  let identifierCount = 0;
  visit(ast, {
    visitIdentifier(path) {
      identifierCount += 1;
      this.traverse(path);
    },
  });
  assert.strictEqual(identifierCount, 3);

  console.log('Contract assertions passed successfully.');
}

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