espree 10.4.0: parse

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 espree.parse in pkg:npm/espree@10.4.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/espree@10.4.0
Demonstrate these symbols/APIs:
  - espree.parse

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:e27d409de41d769c3b09aca38417966c5aec0e0b694a1a424bd9eefc61eed846","contract":["parse parses standard JavaScript script code into an ESTree Program AST node","parse supports ES module syntax when sourceType is module","parse attaches loc and range metadata when options loc and range are enabled","parse collects comments and tokens when comment and tokens options are true","parse supports JSX element parsing when ecmaFeatures jsx is enabled","parse throws SyntaxError on invalid JavaScript syntax with location info","parse throws SyntaxError when using features newer than the configured ecmaVersion"],"goal":"verify espree.parse in pkg:npm/espree@10.4.0","kind":"HOW","packages":["pkg:npm/espree@10.4.0"],"schemaVersion":1,"symbols":["espree.parse"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/espree@10.4.0"],"schemaVersion":1,"subject":"pkg:npm/espree@10.4.0","symbols":["espree.parse"],"verifierAdapter":"node-typescript@1"}

import * as espree from 'espree';

/**
 * Parse JavaScript code into an ESTree-compliant AST.
 * @param {string} code - JavaScript source string
 * @param {object} [options] - Parser options
 * @returns {object} ESTree Program AST node
 */
export function parseScript(code, options = {}) {
  return espree.parse(code, {
    ecmaVersion: 'latest',
    sourceType: 'script',
    ...options,
  });
}

/**
 * Parse JavaScript ES module code into an ESTree-compliant AST.
 * @param {string} code - JavaScript module source string
 * @param {object} [options] - Parser options
 * @returns {object} ESTree Program AST node
 */
export function parseModule(code, options = {}) {
  return espree.parse(code, {
    ecmaVersion: 'latest',
    sourceType: 'module',
    ...options,
  });
}

/**
 * Parse JavaScript code containing JSX syntax into an AST.
 * @param {string} code - JSX source string
 * @param {object} [options] - Parser options
 * @returns {object} ESTree Program AST node
 */
export function parseJSX(code, options = {}) {
  const { ecmaFeatures, ...restOptions } = options;
  return espree.parse(code, {
    ecmaVersion: 'latest',
    sourceType: 'module',
    ecmaFeatures: {
      jsx: true,
      ...ecmaFeatures,
    },
    ...restOptions,
  });
}

/**
 * Parse JavaScript code with attached token and comment metadata.
 * @param {string} code - JavaScript source string
 * @param {object} [options] - Parser options
 * @returns {object} ESTree Program AST node with comments and tokens
 */
export function parseWithTokensAndComments(code, options = {}) {
  return espree.parse(code, {
    ecmaVersion: 'latest',
    comment: true,
    tokens: true,
    loc: true,
    range: true,
    ...options,
  });
}

export { espree };

{
  "name": "sample-espree-parse",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-espree-parse",
      "version": "1.0.0",
      "dependencies": {
        "espree": "10.4.0"
      }
    },
    "node_modules/acorn": {
      "version": "8.18.0",
      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.18.0.tgz",
      "integrity": "sha512-lGq+9yr1/GuAWaVYIHRjvvySG5/4VfKIvC8EWxStPdcDh/Ka7FG3twP6v4d5BkravUilhIAsG4Qj83t02LWUPQ==",
      "license": "MIT",
      "bin": {
        "acorn": "bin/acorn"
      },
      "engines": {
        "node": ">=0.4.0"
      }
    },
    "node_modules/acorn-jsx": {
      "version": "5.3.2",
      "resolved": "https://registry.npmjs.org/acorn-jsx/-/acorn-jsx-5.3.2.tgz",
      "integrity": "sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==",
      "license": "MIT",
      "peerDependencies": {
        "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0"
      }
    },
    "node_modules/eslint-visitor-keys": {
      "version": "4.2.1",
      "resolved": "https://registry.npmjs.org/eslint-visitor-keys/-/eslint-visitor-keys-4.2.1.tgz",
      "integrity": "sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==",
      "license": "Apache-2.0",
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/eslint"
      }
    },
    "node_modules/espree": {
      "version": "10.4.0",
      "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz",
      "integrity": "sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==",
      "license": "BSD-2-Clause",
      "dependencies": {
        "acorn": "^8.15.0",
        "acorn-jsx": "^5.3.2",
        "eslint-visitor-keys": "^4.2.1"
      },
      "engines": {
        "node": "^18.18.0 || ^20.9.0 || >=21.1.0"
      },
      "funding": {
        "url": "https://opencollective.com/eslint"
      }
    }
  }
}

{
  "name": "sample-espree-parse",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "espree": "10.4.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify espree.parse in pkg:npm/espree@10.4.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/espree@10.4.0"
  ],
  "symbols": [
    "espree.parse"
  ]
}

import assert from 'node:assert/strict';
import {
  espree,
  parseScript,
  parseModule,
  parseJSX,
  parseWithTokensAndComments,
} from '../index.js';

// 1. parse parses standard JavaScript script code into an ESTree Program AST node
const scriptAst = parseScript('const greeting = "hello world";\nconst sum = 1 + 2;');
assert.strictEqual(typeof scriptAst, 'object', 'AST must be an object');
assert.strictEqual(scriptAst.type, 'Program', 'AST root type must be Program');
assert.strictEqual(scriptAst.sourceType, 'script', 'sourceType must default to script');
assert.strictEqual(Array.isArray(scriptAst.body), true, 'body must be an array');
assert.strictEqual(scriptAst.body.length, 2, 'body must contain 2 statements');
assert.strictEqual(scriptAst.body[0].type, 'VariableDeclaration');
assert.strictEqual(scriptAst.body[0].kind, 'const');
assert.strictEqual(scriptAst.body[0].declarations[0].id.name, 'greeting');
assert.strictEqual(scriptAst.body[0].declarations[0].init.value, 'hello world');

// 2. parse supports ES module syntax when sourceType is module
const moduleSource = 'import { calculate } from "./math.js";\nexport const result = calculate(10);';
const moduleAst = parseModule(moduleSource);
assert.strictEqual(moduleAst.type, 'Program');
assert.strictEqual(moduleAst.sourceType, 'module');
assert.strictEqual(moduleAst.body.length, 2);
assert.strictEqual(moduleAst.body[0].type, 'ImportDeclaration');
assert.strictEqual(moduleAst.body[0].source.value, './math.js');
assert.strictEqual(moduleAst.body[1].type, 'ExportNamedDeclaration');

// 3. parse attaches loc and range metadata when options loc and range are enabled
const rangeSource = 'let counter = 0;\ncounter += 1;';
const locAst = espree.parse(rangeSource, {
  ecmaVersion: 'latest',
  loc: true,
  range: true,
});
assert.ok(Array.isArray(locAst.range), 'range must be an array of [start, end]');
assert.strictEqual(locAst.range[0], 0);
assert.strictEqual(locAst.range[1], rangeSource.length);
assert.strictEqual(typeof locAst.loc, 'object', 'loc must be an object');
assert.strictEqual(locAst.loc.start.line, 1);
assert.strictEqual(locAst.loc.start.column, 0);
assert.strictEqual(locAst.loc.end.line, 2);
assert.strictEqual(locAst.loc.end.column, 13);

// 4. parse collects comments and tokens when comment and tokens options are true
const annotatedSource = '// leading line comment\n/* block comment */\nconst port = 8080;';
const annotatedAst = parseWithTokensAndComments(annotatedSource);
assert.ok(Array.isArray(annotatedAst.comments), 'comments must be an array');
assert.strictEqual(annotatedAst.comments.length, 2);
assert.strictEqual(annotatedAst.comments[0].type, 'Line');
assert.strictEqual(annotatedAst.comments[0].value.trim(), 'leading line comment');
assert.strictEqual(annotatedAst.comments[1].type, 'Block');
assert.strictEqual(annotatedAst.comments[1].value.trim(), 'block comment');
assert.ok(Array.isArray(annotatedAst.tokens), 'tokens must be an array');
assert.ok(annotatedAst.tokens.length > 0, 'tokens array must not be empty');
assert.strictEqual(annotatedAst.tokens[0].type, 'Keyword');
assert.strictEqual(annotatedAst.tokens[0].value, 'const');

// 5. parse supports JSX element parsing when ecmaFeatures jsx is enabled
const jsxSource = '<Button disabled={false}>Click me</Button>';
const jsxAst = parseJSX(jsxSource);
assert.strictEqual(jsxAst.type, 'Program');
assert.strictEqual(jsxAst.body[0].type, 'ExpressionStatement');
assert.strictEqual(jsxAst.body[0].expression.type, 'JSXElement');
assert.strictEqual(jsxAst.body[0].expression.openingElement.name.name, 'Button');
assert.strictEqual(jsxAst.body[0].expression.openingElement.attributes[0].name.name, 'disabled');
assert.strictEqual(jsxAst.body[0].expression.children[0].type, 'JSXText');
assert.strictEqual(jsxAst.body[0].expression.children[0].value, 'Click me');

// 6. parse throws SyntaxError on invalid JavaScript syntax with location info
assert.throws(() => {
  espree.parse('const = 42;', { ecmaVersion: 'latest' });
}, (err) => {
  return (
    err instanceof SyntaxError &&
    typeof err.lineNumber === 'number' &&
    typeof err.column === 'number' &&
    typeof err.index === 'number'
  );
}, 'Invalid JS syntax must throw SyntaxError with lineNumber, column, and index');

// 7. parse throws SyntaxError when using features newer than the configured ecmaVersion
assert.throws(() => {
  espree.parse('const val = 100;', { ecmaVersion: 5 });
}, (err) => {
  return err instanceof SyntaxError;
}, 'Parsing const in ES5 must throw SyntaxError');

console.log('Contract verification finished successfully: all espree.parse assertions passed.');