estree-walker 3.0.3: asyncWalk

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 estree-walker.asyncWalk in pkg:npm/estree-walker@3.0.3
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/estree-walker@3.0.3
Demonstrate these symbols/APIs:
  - estree-walker.asyncWalk

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:b5753bcda1c213933c6216c5a5d601544830363f092718ca7170b76d3948ee0b","contract":["asyncWalk exports an async function that traverses an ESTree AST asynchronously","asyncWalk visits AST nodes in enter and leave order asynchronously","asyncWalk passes node, parent, prop, and index to visitor handlers","asyncWalk this.skip skips descending into child nodes of current AST node","asyncWalk this.replace substitutes matched AST node in parent structure asynchronously","asyncWalk this.remove deletes matched AST node from parent array asynchronously","filterNodesAsync and transformNodesAsync helper utilities query and mutate AST nodes using asyncWalk"],"goal":"verify estree-walker.asyncWalk in pkg:npm/estree-walker@3.0.3","kind":"HOW","packages":["pkg:npm/estree-walker@3.0.3"],"schemaVersion":1,"symbols":["estree-walker.asyncWalk"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"node","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/estree-walker@3.0.3"],"schemaVersion":1,"subject":"pkg:npm/estree-walker@3.0.3","symbols":["estree-walker.asyncWalk"],"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-estree-walker",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-estree-walker",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "estree-walker": "3.0.3"
      }
    },
    "node_modules/@types/estree": {
      "version": "1.0.9",
      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.9.tgz",
      "integrity": "sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==",
      "license": "MIT"
    },
    "node_modules/estree-walker": {
      "version": "3.0.3",
      "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-3.0.3.tgz",
      "integrity": "sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==",
      "license": "MIT",
      "dependencies": {
        "@types/estree": "^1.0.0"
      }
    }
  }
}

{
  "name": "csx-sample-estree-walker",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "estree-walker": "3.0.3"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify estree-walker.asyncWalk in pkg:npm/estree-walker@3.0.3",
  "kind": "HOW",
  "packages": [
    "pkg:npm/estree-walker@3.0.3"
  ],
  "symbols": [
    "estree-walker.asyncWalk"
  ]
}

import { asyncWalk } from 'estree-walker';

export { asyncWalk };

/**
 * Traverses an ESTree AST asynchronously and collects nodes matching an async predicate.
 *
 * @param {object} ast - The AST root node.
 * @param {(node: object, parent: object | null) => Promise<boolean>} predicate - Async test function.
 * @returns {Promise<object[]>} Matching AST nodes.
 */
export async function filterNodesAsync(ast, predicate) {
  const matches = [];
  await asyncWalk(ast, {
    async enter(node, parent) {
      if (await predicate(node, parent)) {
        matches.push(node);
      }
    },
  });
  return matches;
}

/**
 * Transforms an ESTree AST asynchronously by applying an async replacer function.
 *
 * @param {object} ast - The AST root node.
 * @param {(node: object) => Promise<object | null | undefined>} transform - Async transformer returning replacement node, or null to remove.
 * @returns {Promise<object | null>} The transformed AST.
 */
export async function transformNodesAsync(ast, transform) {
  return await asyncWalk(ast, {
    async enter(node) {
      const result = await transform(node);
      if (result === null) {
        this.remove();
      } else if (result !== undefined && result !== node) {
        this.replace(result);
      }
    },
  });
}

import { strict as assert } from 'node:assert';
import { asyncWalk, filterNodesAsync, transformNodesAsync } from '../src/index.mjs';

// 1. Verify asyncWalk is exported as a function
assert.equal(typeof asyncWalk, 'function');

// 2. Verify asyncWalk visits AST nodes in enter and leave order asynchronously
const sampleAst = {
  type: 'Program',
  body: [
    {
      type: 'VariableDeclaration',
      declarations: [
        {
          type: 'VariableDeclarator',
          id: { type: 'Identifier', name: 'count' },
          init: { type: 'Literal', value: 10 },
        },
      ],
      kind: 'const',
    },
  ],
};

const enterSequence = [];
const leaveSequence = [];
await asyncWalk(sampleAst, {
  async enter(node) {
    await new Promise((resolve) => setTimeout(resolve, 1));
    enterSequence.push(node.type);
  },
  async leave(node) {
    await new Promise((resolve) => setTimeout(resolve, 1));
    leaveSequence.push(node.type);
  },
});

assert.deepEqual(enterSequence, [
  'Program',
  'VariableDeclaration',
  'VariableDeclarator',
  'Identifier',
  'Literal',
]);
assert.deepEqual(leaveSequence, [
  'Identifier',
  'Literal',
  'VariableDeclarator',
  'VariableDeclaration',
  'Program',
]);

// 3. Verify enter handler receives node, parent, prop, and index
let identifierParentType = null;
let identifierProp = null;
let identifierIndex = null;

await asyncWalk(sampleAst, {
  async enter(node, parent, prop, index) {
    if (node.type === 'Identifier') {
      identifierParentType = parent?.type;
      identifierProp = prop;
      identifierIndex = index;
    }
  },
});

assert.equal(identifierParentType, 'VariableDeclarator');
assert.equal(identifierProp, 'id');
assert.equal(identifierIndex, null);

// 4. Verify this.skip skips descending into child nodes during asyncWalk
const skipAst = {
  type: 'Program',
  body: [
    {
      type: 'FunctionDeclaration',
      id: { type: 'Identifier', name: 'calculate' },
      body: {
        type: 'BlockStatement',
        body: [
          { type: 'ReturnStatement', argument: { type: 'Literal', value: 1 } },
        ],
      },
    },
  ],
};

const visitedInSkip = [];
await asyncWalk(skipAst, {
  async enter(node) {
    visitedInSkip.push(node.type);
    if (node.type === 'BlockStatement') {
      this.skip();
    }
  },
});

assert.deepEqual(visitedInSkip, [
  'Program',
  'FunctionDeclaration',
  'Identifier',
  'BlockStatement',
]);

// 5. Verify this.replace substitutes matched node asynchronously
const replaceAst = {
  type: 'Program',
  body: [
    {
      type: 'ExpressionStatement',
      expression: { type: 'Identifier', name: 'beforeReplace' },
    },
  ],
};

await asyncWalk(replaceAst, {
  async enter(node) {
    if (node.type === 'Identifier' && node.name === 'beforeReplace') {
      await new Promise((resolve) => setTimeout(resolve, 1));
      this.replace({ type: 'Identifier', name: 'afterReplace' });
    }
  },
});

assert.equal(replaceAst.body[0].expression.name, 'afterReplace');

// 6. Verify this.remove deletes matched node from parent array asynchronously
const removeAst = {
  type: 'Program',
  body: [
    { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'a' } },
    { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'b' } },
    { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'c' } },
  ],
};

await asyncWalk(removeAst, {
  async enter(node) {
    if (node.type === 'ExpressionStatement' && node.expression?.name === 'b') {
      await new Promise((resolve) => setTimeout(resolve, 1));
      this.remove();
    }
  },
});

assert.equal(removeAst.body.length, 2);
assert.equal(removeAst.body[0].expression.name, 'a');
assert.equal(removeAst.body[1].expression.name, 'c');

// 7. Verify helper functions filterNodesAsync and transformNodesAsync
const foundIdentifiers = await filterNodesAsync(sampleAst, async (n) => n.type === 'Identifier');
assert.equal(foundIdentifiers.length, 1);
assert.equal(foundIdentifiers[0].name, 'count');

const astToTransform = {
  type: 'Program',
  body: [
    { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'target' } },
    { type: 'ExpressionStatement', expression: { type: 'Identifier', name: 'obsolete' } },
  ],
};

await transformNodesAsync(astToTransform, async (node) => {
  if (node.type === 'Identifier' && node.name === 'target') {
    return { type: 'Identifier', name: 'transformed' };
  }
  if (node.type === 'ExpressionStatement' && node.expression?.name === 'obsolete') {
    return null;
  }
});

assert.equal(astToTransform.body.length, 1);
assert.equal(astToTransform.body[0].expression.name, 'transformed');

console.log('CONTRACT PASS: estree-walker.asyncWalk verified');