esquery 1.7.0: esquery

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 esquery in pkg:npm/esquery@1.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/esquery@1.7.0
Demonstrate these symbols/APIs:
  - esquery

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:a24f53beebf329a04033937986fc658ffade4986d4b88ee8348175dff3aab8fe","contract":["assert esquery returns an array of matching AST nodes for a node type selector","assert esquery returns matching AST nodes for attribute selectors","assert esquery returns matching AST nodes for child and descendant selectors","assert esquery.parse parses selector strings into attribute and compound selector ASTs","assert esquery.match executes a pre-parsed selector AST against an AST","assert esquery.query performs the same AST query as the main esquery function","assert esquery returns an empty array when no AST nodes match the selector"],"goal":"verify esquery in pkg:npm/esquery@1.7.0","kind":"HOW","packages":["pkg:npm/esquery@1.7.0"],"schemaVersion":1,"symbols":["esquery"]},"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/esquery@1.7.0"],"schemaVersion":1,"subject":"pkg:npm/esquery@1.7.0","symbols":["esquery"],"verifierAdapter":"node-typescript@1"}

const esquery = require('esquery');

/**
 * Queries an AST using a selector string.
 *
 * @param {object} ast - The AST node or tree to query.
 * @param {string} selector - The esquery selector string.
 * @returns {Array<object>} Array of matching AST nodes.
 */
function queryAst(ast, selector) {
  return esquery(ast, selector);
}

/**
 * Parses an esquery selector into a selector AST and matches it against an AST.
 *
 * @param {object} ast - The AST node or tree to query.
 * @param {string} selector - The esquery selector string.
 * @returns {Array<object>} Array of matching AST nodes.
 */
function queryWithParsedSelector(ast, selector) {
  const parsed = esquery.parse(selector);
  return esquery.match(ast, parsed);
}

module.exports = {
  queryAst,
  queryWithParsedSelector,
  esquery,
};

{
  "name": "sample-esquery",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-esquery",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "esquery": "1.7.0"
      }
    },
    "node_modules/esquery": {
      "version": "1.7.0",
      "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.7.0.tgz",
      "integrity": "sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==",
      "license": "BSD-3-Clause",
      "dependencies": {
        "estraverse": "^5.1.0"
      },
      "engines": {
        "node": ">=0.10"
      }
    },
    "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-esquery",
  "version": "1.0.0",
  "description": "Clean-room sample verifying esquery in pkg:npm/esquery@1.7.0",
  "main": "index.js",
  "license": "MIT-0",
  "dependencies": {
    "esquery": "1.7.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify esquery in pkg:npm/esquery@1.7.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/esquery@1.7.0"
  ],
  "symbols": [
    "esquery"
  ]
}

import assert from 'node:assert';
import esquery from 'esquery';
import { queryAst, queryWithParsedSelector } from '../index.js';

// Setup sample ESTree AST
const ast = {
  type: 'Program',
  body: [
    {
      type: 'VariableDeclaration',
      kind: 'const',
      declarations: [
        {
          type: 'VariableDeclarator',
          id: { type: 'Identifier', name: 'count' },
          init: { type: 'Literal', value: 10, raw: '10' }
        }
      ]
    },
    {
      type: 'FunctionDeclaration',
      id: { type: 'Identifier', name: 'calculateTotal' },
      params: [
        { type: 'Identifier', name: 'price' },
        { type: 'Identifier', name: 'tax' }
      ],
      body: {
        type: 'BlockStatement',
        body: [
          {
            type: 'ReturnStatement',
            argument: {
              type: 'BinaryExpression',
              operator: '+',
              left: { type: 'Identifier', name: 'price' },
              right: { type: 'Identifier', name: 'tax' }
            }
          }
        ]
      }
    }
  ]
};

// 1. esquery returns an array of matching nodes for a node type selector
const functionNodes = esquery(ast, 'FunctionDeclaration');
assert(Array.isArray(functionNodes), 'esquery must return an array');
assert.strictEqual(functionNodes.length, 1);
assert.strictEqual(functionNodes[0].id.name, 'calculateTotal');

const helperFunctionNodes = queryAst(ast, 'FunctionDeclaration');
assert.strictEqual(helperFunctionNodes.length, 1);
assert.strictEqual(helperFunctionNodes[0].id.name, 'calculateTotal');

// 2. esquery returns matching nodes for attribute selectors
const constDeclarations = esquery(ast, 'VariableDeclaration[kind="const"]');
assert.strictEqual(constDeclarations.length, 1);
assert.strictEqual(constDeclarations[0].kind, 'const');

const binaryPlus = esquery(ast, 'BinaryExpression[operator="+"]');
assert.strictEqual(binaryPlus.length, 1);
assert.strictEqual(binaryPlus[0].operator, '+');

// 3. esquery returns matching nodes for descendant and child selectors
const childIdentifiers = esquery(ast, 'FunctionDeclaration > Identifier');
assert.strictEqual(childIdentifiers.length, 3);

const returnStatements = esquery(ast, 'FunctionDeclaration ReturnStatement');
assert.strictEqual(returnStatements.length, 1);
assert.strictEqual(returnStatements[0].type, 'ReturnStatement');

// 4. esquery.parse parses selector string into a selector AST
const parsedAttributeSelector = esquery.parse('[name="price"]');
assert.strictEqual(typeof parsedAttributeSelector, 'object');
assert.strictEqual(parsedAttributeSelector.type, 'attribute');
assert.strictEqual(parsedAttributeSelector.name, 'name');
assert.strictEqual(parsedAttributeSelector.value.value, 'price');

const parsedCompoundSelector = esquery.parse('Identifier[name="price"]');
assert.strictEqual(parsedCompoundSelector.type, 'compound');
assert.strictEqual(parsedCompoundSelector.selectors.length, 2);

// 5. esquery.match executes a pre-parsed selector AST against an AST
const matchedNodes = esquery.match(ast, parsedCompoundSelector);
assert.strictEqual(matchedNodes.length, 2);
assert.strictEqual(matchedNodes[0].name, 'price');
assert.strictEqual(matchedNodes[1].name, 'price');

const helperMatchedNodes = queryWithParsedSelector(ast, 'Identifier[name="price"]');
assert.strictEqual(helperMatchedNodes.length, 2);
assert.strictEqual(helperMatchedNodes[0].name, 'price');
assert.strictEqual(helperMatchedNodes[1].name, 'price');

// 6. esquery.query performs the same query as the main esquery function
const queriedNodes = esquery.query(ast, 'VariableDeclarator');
assert.strictEqual(queriedNodes.length, 1);
assert.strictEqual(queriedNodes[0].id.name, 'count');

// 7. esquery returns empty array when no AST nodes match selector
const unmatchedNodes = esquery(ast, 'ClassDeclaration');
assert(Array.isArray(unmatchedNodes), 'esquery must return an array when nothing matches');
assert.strictEqual(unmatchedNodes.length, 0);

console.log('All esquery contract assertions passed.');