SkillAgentSearch skills...

Esmeta

ECMAScript Specification (ECMA-262) Metalanguage

GenerateConvertImprove

Install / Use

/learn @es-meta/Esmeta
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

test license release prs slack site doc

ESMeta

ESMeta is an ECMAScript Specification Metalanguage. This framework extracts a mechanized specification from a given version of ECMAScript/JavaScript specification (ECMA-262) and automatically generates language-based tools.

Table of Contents

Installation Guide

We explain how to install ESMeta with the necessary environment settings from scratch. Our framework is developed in Scala, which works on JDK 17+. So before installation, please install JDK 17+ and sbt, an interactive build tool for Scala.

Download ESMeta

$ git clone https://github.com/es-meta/esmeta.git

Environment Setting

Insert the following commands to ~/.bashrc (or ~/.zshrc):

# for ESMeta
export ESMETA_HOME="<path to ESMeta>" # IMPORTANT!!!
export PATH="$ESMETA_HOME/bin:$PATH" # for executables `esmeta` and etc.
source $ESMETA_HOME/.completion # for auto-completion

The <path to ESMeta> should be the absolute path of the ESMeta repository.

Installation of ESMeta using sbt

Please type the following command to 1) update the git submodules, 2) generate binary file bin/esmeta, and 3) apply the .completion for auto-completion.

$ cd esmeta && git submodule update --init && sbt assembly && source .completion

If you see the following message, ESMeta is successfully installed:

$ esmeta
# Welcome to ESMeta v0.7.3 - ECMAScript Specification Metalanguage.
# Please type `esmeta help` to see the help message.

Basic Commands

You can run this framework with the following command:

$ esmeta <command> <option>* <filename>*

It supports the following commands:

  • help shows help messages.
  • extract extracts specification model from ECMA-262 (ecma262/spec.html).
  • compile compiles a specification to an IR program.
  • build-cfg builds a control-flow graph (CFG) from an IR program.
  • tycheck performs a type analysis of ECMA-262.
  • parse parses an ECMAScript file.
  • eval evaluates an ECMAScript file.
  • web starts a web server for an ECMAScript double debugger.
  • test262-test tests Test262 tests with harness files (default: tests/test262).
  • inject injects assertions to check final state of an ECMAScript file.
  • mutate mutates an ECMAScript program.
  • analyze analyzes an ECMAScript file using meta-level static analysis. (temporarily removed)
  • dump-debugger dumps the resources required by the standalone debugger. (for internal use)
  • dump-visualizer dumps the resources required by the visualizer. (for internal use)

and global options:

  • -silent does not show final results.
  • -error shows error stack traces.
  • -status exits with status.
  • -time displays the duration time.
  • -test262dir={string} sets the directory of Test262 (default: $ESMETA_HOME/tests/test262).

If you want to see the detailed help messages and command-specific options, please use the help command:

# show help messages for all commands
$ esmeta help

# show help messages for specific commands with more details
$ esmeta help <command>

Please use the build-cfg command to extract a mechanized specification as a control-flow graph from ECMA-262:

$ esmeta build-cfg
# ========================================
#  extract phase
# ----------------------------------------
# ========================================
#  compile phase
# ----------------------------------------
# ========================================
#  build-cfg phase
# ----------------------------------------
# 0: def <BUILTIN>:INTRINSICS.SyntaxError(...): Unknown {
#   ...
# }
# 1: def <INTERNAL>:BuiltinFunctionObject.Construct(...): Normal[Object] | Abrupt[throw] {
#   ...
# }
# ...

The build-cfg command consists of three phases:

  1. The extract phase extracts specification model (esmeta.spec.Spec) from ECMA-262 (spec.html).
  2. The compile phase compiles it into a program (esmeta.ir.Program) in IRES, an Intermediate Representations for ECMAScript Specification.
  3. The build-cfg phase builds a control-flow graph (esmeta.cfg.CFG) for a given IRES program.

You can extract mechanized specifications from other versions of ECMA-262 with the -extract:target option. Please enter any git tag/branch names or commit hash as an input of the option:

# extract a mechanized specification from the origin/main branch version of ECMA-262
$ esmeta build-cfg -extract:target=origin/main

# extract a mechanized specification from the 2c78e6f commit version of ECMA-262
$ esmeta build-cfg -extract:target=2c78e6f

Parsing and Executing ECMAScript files

After extracting mechanized specifications from ECMA-262, you can parse or execute ECMAScript/JavaScript programs. For example, consider the following example JavaScript file:

// example.js
let x; x ??= class {}; function* f() {}

You can parse or execute it with parse and eval commands.

# parse example.js
$ esmeta parse example.js

# execute example.js
$ esmeta eval example.js

Executing Test262 tests

ESMeta supports the execution of Test262 tests to check the conformance between Test262 and ECMA-262.

# run all the applicable Test262 tests
$ esmeta test262-test
# ...
# ========================================
#  test262-test phase
# ----------------------------------------
# - harness                       :    96 tests are removed
# ...
# ----------------------------------------
# - total: 31,537 available tests
#   - normal: 31,537 tests
#   - error: 0 tests
# ----------------------------------------
# ...

If you want to execute specific Test262 files or directories, please list their paths as arguments:

# run Test262 tests in a given directory
$ esmeta test262-test tests/test262/test/language/expressions/addition

Supported Features

ESMeta supports other features utilizing mechanized specifications, including 1) exemplify specification with ECMA Visualizer, 2) interactive execution of ECMAScript/JavaScript file with a double debugger, 3) conformance test synthesizer, 4) type analysis of ECMA-262, and 5) meta-level static analysis for ECMAScript/JavaScript files. All of them utilize mechanized specifications from ECMA-262. Thus, ESMeta always extracts mechanized specifications as control-flow graphs before performing these features.

Specification Exemplified with ECMA Visualizer

[!NOTE]

A short introduction video for ECMA Visualizer and Double Debugger is available.

<img width="1150" alt="ecma-visualizer" src="https://github.com/user-attachments/assets/733403f5-03cc-4465-a773-e57d46d35180" />

ECMA Visualizer is a Chrome Extension that helps users understand specifications by displaying rich information alongside the ecma-262 web documentation, collected through pre-fuzzing/measurement using ESMeta. This allows users to see helpful examples directly within the ecma-262 web documents. It provides the following features:

  • Viewing minimal JavaScript program that passes through specific algorithm steps or control flow branches (ReturnIfAbrupt, denoted as ?) in the specification
  • Viewing conformance tests (from test262) that pass through selected steps
  • Filtering displayed JS code using callpath
  • One-click debugging capability to execute the displayed minimal JS code, resuming from the selected step

Interactive Execution with ECMAScript Double Debugger

[!NOTE]

A short introduction video for ECMA Visualizer and Double Debugger is available.

ECMAScript Double Debugger extends the ECMAScript/JavaScript interpreter in ESMeta to help you understand how a JavaScript Program runs according to ECMA-262. Currently, it is in an beta stage and supports following features:

  • Step-by-step execution of ECMA-262 algorithms
  • Line-by-line execution of

es-meta

View profile

View on GitHub
GitHub Stars257
CategoryProduct
Updated1d ago
Forks24
es-meta/esmeta

Languages

Scala

Security Score

100/100

Audited on Apr 8, 2026

No findings