yowainwright / es-check

Checks the version of ES in JavaScript files with simple shell commands 🏆

---

Check JavaScript files ES version against a specified ES version 🏆

---

ES Check ✔️

---

ES Check checks JavaScript files against a specified version of ECMAScript (ES) with a shell command. If a specified file's ES version doesn't match the ES version argument passed in the ES Check command, ES Check will throw an error and log the files that didn't match the check.

Ensuring that JavaScript files can pass ES Check is important in a modular and bundled world. Read more about why.

---

Version 7 🎉

Thanks to the efforts of Anders Kaseorg, ES Check has switched to Commander! There appears to be no breaking issues but this update is being published as a major release for your ease-of-use. Please reach out with observations or pull requests features/fixes!

This update was made for security purposes—dependencies not being maintained.

Thanks to Anders for this deeper fix, to Pavel Starosek for the initial issue and support, and to Alexander Pepper for digging into this issue more!

---

Get Started   Why ES Check?   Usage   Walk Through   API   Debugging   Contributing   Issues Roadmap

---

Get Started

Install

npm i es-check --save-dev   # locally
npm i es-check -g           # or globally

Check if an array or glob of files matches a specified ES version.

• Note: adds quotation around globs. Globs are patterns like so, <something>/*.js.

es-check es5 './vendor/js/*.js' './dist/**/*.js'

• The ES Check script (above) checks /dist/*.js files to see if they're ES5. It throws an error and logs files are that do not pass the check.

---

Why ES Check?

In modern JavaScript builds, files are bundled up so they can be served in an optimized manner in the browsers. It is assumed by developers that future JavaScript—like ES8 will be transpiled (changed from future JavaScript to current JavaScript) appropriately by a tool like Babel. Sometimes there is an issue where files are not transpiled. There was no efficient way to test for files that weren't transpiled—until now. That's what ES Check does.

---

Walk through

The images below demonstrate command line scripts and their corresponding logged results.

Pass

Fail

ES Check is run above with node commands. It can also be run within npm scripts, ci tools, or testing suites.

---

API

ES Check provides the necessities. It accepts its place as a JavaScript matcher/tester.

General Information

# USAGE

index.js es-check <ecmaVersion> [files...]

Arguments

<ecmaVersion> 'define the ECMAScript version to check for against a glob of JavaScript files' required
[files...] 'a glob of files to test the ECMAScript version against' required

Options

Modules Flag

--module use ES modules, default false

Allow Hash Bang

--allow-hash-bang supports files that start with hash bang, default false

Not

--not=folderName1,folderName2 An array of file/folder names or globs that you would like to ignore. Defaults to `[]`.

Global Options

-h, --help         Display help
-V, --version      Display version
--no-color         Disable colors
--quiet            Quiet mode - only displays warn and error messages
-v, --verbose      Verbose mode - will also output debug messages

---

Usage

ES Check is a shell command CLI. It is run in shell tool like Terminal, ITerm, or Hyper. It takes in two arguments: an ECMAScript version (<ECMAScript version>) and files ([files]) in globs.

Here are some example of es check scripts that could be run:

# globs
es-check ./js/*.js

# array of arguments
es-check ./js/*.js ./dist/*.js

---

Configuration

If you're using a consistent configuration, you can create a .escheckrc file in JSON format with the ecmaVersion and files arguments so you can conveniently run es-check standalone from the command line.

Here's an example of what an .escheckrc file will look like:

{
  "ecmaVersion": "es6",
  "module": false,
  "files": "./dist/**/*.js",
  "not": ["./dist/skip/*.js"]
}

⚠️ NOTE: Using command line arguments while there is an .escheckrc file in the project directory will override the configuration values in .escheckrc.

Debugging

As of ES-Check version 2.0.2, a better debugging interface is provided. When a file errors, An error object will be logged with:

• the erroring file
• the error
• the error stack

⚠️ NOTE: Error logs are from the Acorn parser while parsing JavaScript related to specific versions of ECMAScript. This means error messaging is not specific to ECMAScript version. It still offers context into parsing issues!

---

Acknowledgements

ES Check is a small utility using powerful tools that Isaac Z. Schlueter, Marijn Haverbeke, and Matthias Etienne built. ES Checker by Ruan YiFeng checks the JavaScript version supported within a browser at run time. ES Check offers similar feedback to ES Checker but at build time and is specific to the product that is using it. ES Check was started after reading this post about [deploying es2015 code to production today] by Philip Walton.

---

Contributing

ES Check has 3 main dependencies: acorn, glob, and caporal. To contribute, file an issue or submit a pull request. To setup local development, run ./bin/setup.sh or open the devcontainer in VSCode.

Contributors

• Jeff Wainwright
• Brian Gonzalez
• Jon Ong
• Suhas Karanth
• Ben Junya
• Jeff Barczewski
• Brandon Casey

Roadmap

• Provide compilation step to support esm
  • non-user-facing
  • required to keep package dependencies up-to-date as more dependencies are ESM-only
• Provide checks for theoretical keywork words
  • Things like Map and Object.assign are not keywords that fail ECMAScript compilation depending on specific versions of ECMAScript. However, they hint at additions to ECMAScript that previous version did not support.
  • This feature will enhance an already built-in confiration feature to provide more out-of-the-box support for ECMAScript checking.
  • If enabled, this feature will warn (or fail) based on theoretical ECMAScript keywords.

es-check's Issues

Flag option for specifying files

Requested Update

Add a way to describe files via a flag (something like -f/--files).

Why Is This Update Needed?

The would make it easier to work with a configuration file in the case where you want to vary which files you check without changing the ES version. Having files only come via positional arguments forces users to redeclare the ES version unnecessarily (getting error: Invalid ecmaScript version, please pass a valid version, use --help for help if they try to omit it and go straight to file paths).

Example

Say you have a configuration file like this:

{
  "ecmaVersion": "es6",
  "module": false,
  "files": "./dist/**/*.js",
  "not": ["./dist/skip/*.js"]
}

If you want to change which files are checked, you currently have to do this, duplicating the ES version declaration and introducing the possibility for drift:

es-check es6 './dist/app/**/*.js'

With a flag, you could do this:

es-check -f './dist/app/**/*.js'

This would be a small QoL improvement. The existing functionality would still be the primary way to declare files and would take precedence over a flag declaration in the event of duplication.

I'm happy to contribute this if the idea is accepted.

Are There Examples Of This Requested Update Elsewhere?

Read about references issues here. Provide paragraph text responses to each header.

`SyntaxError: Unexpected token` reported when checking `es2019` with dependency declaring class field

Requested Update

The following code in a thirdparty library (@lingui/core) used by our application code causes errors when running es-check es2019 \"./dist/*.js\" --module against our bundles:

class EventEmitter {
  _events = {}; // This line causes the problem
  ...
}

The emitted error is:

SyntaxError: Unexpected token (114:32617)
    at Parser.pp$4.raise (C:\app\node_modules\acorn\dist\acorn.js:3460:15)
    at Parser.pp$9.unexpected (C:\app\node_modules\acorn\dist\acorn.js:761:10)
    at Parser.pp$9.expect (C:\app\node_modules\acorn\dist\acorn.js:755:28)
    at Parser.pp$5.parseMethod (C:\app\node_modules\acorn\dist\acorn.js:3222:10)
    at Parser.pp$8.parseClassMethod (C:\app\node_modules\acorn\dist\acorn.js:1516:37)
    at Parser.pp$8.parseClassElement (C:\app\node_modules\acorn\dist\acorn.js:1474:12)
    at Parser.pp$8.parseClass (C:\app\node_modules\acorn\dist\acorn.js:1392:26)
    at Parser.pp$8.parseStatement (C:\app\node_modules\acorn\dist\acorn.js:907:19)
    at Parser.pp$8.parseBlock (C:\app\node_modules\acorn\dist\acorn.js:1237:23)
    at Parser.pp$5.parseFunctionBody (C:\app\node_modules\acorn\dist\acorn.js:3286:24)

As far as I know, the affected line in EventEmitter is valid JS code, thus the error reported seems to be a false positive, isn't it?

Why Is This Update Needed?

Because es-check causes valid JS code to be reported as errors.

Are There Examples Of This Requested Update Elsewhere?

No

"Must provide pattern" error when using `--module` in 6.1.0

Requested Update

I get a "must provide pattern" error for this command after upgrading to 6.1.0 from 6.0.0, without any other changes.

node ./node_modules/.bin/es-check es2015 --module 'dist/auth0-spa-js.production.esm.js'

I added some logging to see what's going on, it looks like the filename isn't being passed through the options:

.action(({ logger, args, options }) => {
    const configFilePath = path.resolve(process.cwd(), '.escheckrc')

    // Some basic logging
    console.log(options)
    console.log(args);

    // ...
})

Yields:

{ module: false, allowHashBang: false }
{ ecmaVersion: 'es2015' }

Not specifying --module sends the filename correctly, but of course the command fails.

{ module: false, allowHashBang: false }
{
  ecmaVersion: 'es2015',
  files: [ 'dist/auth0-spa-js.production.esm.js' ]
}

Could this upgrade have caused it?

Why Is This Update Needed?

Would like to be able to use 6.1.0 and generally keep up to date, otherwise I can pin to 6.0.0.

Are There Examples Of This Requested Update Elsewhere?

I couldn't find one, but apologies if it's a known issue.

Read about references issues here. Provide paragraph text responses to each header.

replaceAll is not supported

Requested Update

When we run es-check against a file that includes replaceAll, es-check says the file is valid es5.

Why Is This Update Needed?

replaceAll is an es2021 feature, and so should be flagged when included in an es5 file.

Are There Examples Of This Requested Update Elsewhere?

No.

Cannot use this project with `yarn` or `npm`

When upgradint to v6.2.0, this error occurs:

╔═════════════════════════════════════════════════════════════╗
║                                                             ║
║   Use "pnpm install" for installation in this project.      ║
║                                                             ║
║   If you don't have pnpm, install it via "npm i -g pnpm".   ║
║   For more details, go to https://pnpm.js.org/              ║
║                                                             ║
╚═════════════════════════════════════════════════════════════╝

Why you are requiring pnpm?

https://github.com/arthurfiorette/fast-defer/runs/4980449823?check_suite_focus=true

Document what checks are performed

Requested Update

It would be great if the README could give an overview of what checks are actually being performed - does es-check only look at syntax, or does it also attempt to look for access to library functions from newer ES versions?

Why Is This Update Needed?

It's unclear what categories of checks the tool attempts to perform

Are There Examples Of This Requested Update Elsewhere?

#37 is slightly related, as it's unclear whether that's a bug or just an intentional ommission

Error when checking es9 code

Running es-check es9 on the following code fails on line } catch {:

try {
    ...
} catch {
    ...
}

error: SyntaxError: Unexpected token (3:8)

es-check passes when re-write to } catch (ex) {

Unexpected token error when using static class properties

Description

When running es-check on a file where static class properties are used, we get an unexpected token error directly after the identifier of a static property.

This is the stack-trace that occurs:

error: ES-Check: there were 1 ES version matching errors.
info: 
          ES-Check Error:
          ----
          · erroring file: index.js
          · error: SyntaxError: Unexpected token (2:11)
          · see the printed err.stack below for context
          ----

          SyntaxError: Unexpected token (2:11)
    at pp$4.raise (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:3460:15)
    at pp$9.unexpected (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:761:10)
    at pp$9.expect (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:755:28)
    at pp$5.parseMethod (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:3222:10)
    at pp$8.parseClassMethod (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:1516:37)
    at pp$8.parseClassElement (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:1474:12)
    at pp$8.parseClass (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:1392:26)
    at pp$8.parseStatement (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:907:19)
    at pp$8.parseTopLevel (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:818:23)
    at Parser.parse (/.../node_modules/es-check/node_modules/acorn/dist/acorn.js:590:17)

based on the stack-trace I assume that the class property is mistakenly parsed as a class method as there is an invocation of parseClassMethod() in the middle of the trace. As the error occurs right after the identifier (at the whitespace character) I think the token expected by the method would be a (, hence the unexpected token error. Static class methods are parsed without any issue.

Repro steps

1. create index.js file
2. define a class with a static property inside the file:

class Example {
  static x = "y";
}

3. run es-check es10 /path/to/index.js

Detect use of RegExp `\p` escape sequence

Requested Update

Detect and warn about use of the \p Regexp escape sequence in unsupported environments

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Unicode_character_class_escape

Why Is This Update Needed?

We recently managed to ship broken code after switching from babel to swc because the \p regex escape sequence was being used, and unlike babel swc doesn't translate them - so es-check was unable to warn us that the code would be incompatible

Are There Examples Of This Requested Update Elsewhere?

n/a

`Cannot read property 'includes' of undefined` after updating to 5.2.1

Requested Update

Latest version crashes for https://github.com/PostHog/posthog-js/ repo. 5.2.0 continues working.

Stack trace:

⟩ npx es-check es5 dist/{array,module}.js -v                         09:42:16

TypeError: Cannot read property 'includes' of undefined
    at /home/macobo/backups/2/projects/posthog-js/node_modules/es-check/index.js:127:16
    at Array.reduce (<anonymous>)
    at Command._action (/home/macobo/backups/2/projects/posthog-js/node_modules/es-check/index.js:126:49)
    at Command._run (/home/macobo/backups/2/projects/posthog-js/node_modules/caporal/lib/command.js:483:42)
    at Program._run (/home/macobo/backups/2/projects/posthog-js/node_modules/caporal/lib/program.js:183:16)
    at Program.parse (/home/macobo/backups/2/projects/posthog-js/node_modules/caporal/lib/program.js:289:17)
    at Object.<anonymous> (/home/macobo/backups/2/projects/posthog-js/node_modules/es-check/index.js:202:6)
    at Module._compile (internal/modules/cjs/loader.js:1063:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1092:10)
    at Module.load (internal/modules/cjs/loader.js:928:32)
    at Function.Module._load (internal/modules/cjs/loader.js:769:14)
    at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:72:12)
    at /home/macobo/.nvm/versions/node/v14.15.0/lib/node_modules/npm/node_modules/libnpx/index.js:268:14

Potential problematic commit: 2922e7d#diff-e727e4bdf3657fd1d798edcd6b099d6e092f8573cba266154583a746bba0f346R127

es-check es5 no match destructuring assignment

hi, it seem that es-check doesn`t match destructuring assignment in es5.

es-check version 6.0.0

./code/script.js

let [a1, a2, a3] = [1, 2, 3]

run script

es-check es5 ./code/*.js

the stdout is
ES-Check: there were no ES version matching errors!

es-check es5 no match destructuring assignment which is es6 syntax.

Is this a bug ?

Add `es2022` and `es2023` support

Requested Update

Add es2022 and es2023 support.

Why Is This Update Needed?

acorn already supports both es2022 and es2023, but they're filtered by the es-check ECMA version check.

Are There Examples Of This Requested Update Elsewhere?

Not sure, if this is relevant.

The output for a successful ES-Check run is logged as an error

es-check/index.js

Line 203 in 2a5eefd

logger.error(`ES-Check: there were no ES version matching errors! 🎉`)

Is this by design? I can submit a PR switching this to be an info log if required. There is a PR on the archived project that wraps this log with the quiet flag to obey the quiet setting, but I would think correctly info logging would be more correct as this is not an error being logged.

Use browserslist to infer ES version to check against

Requested Update

It would be great if a browserslist config could be used to infer which ES version to check against

Related issue: obahareth/are-you-es5#64

Why Is This Update Needed?

Many front-end tools (e.g. babel) use the common browserslist configuration to determine which browsers to target. Before I ship my code to production, I would like to verify that the transpiled code indeed supports the ES version inferred by my supported browsers list.

Are There Examples Of This Requested Update Elsewhere?

No

Read about references issues here. Provide paragraph text responses to each header.

Perform es-check for dependencies in`packages.json`

Requested Update

Allow es-check to check individual modules located in node_modules folder with their nested dependencies in a similar way like are-you-es5 do it.

Scenario:

• I have a frontend react project with dependencies in package.json
• One of those dependencies package-example-in-es2022 includes es2022 code i.e. nullish coalescing
• When I run webpack build, es2022 code in my project gets transpiled by babel, but dependencies from node_modules are not (unless specified in the config), so package-example-in-es2022 with nullish coalescing will cause an issue in browsers like < Chrome 80, < Firefox 72, < Opera 67, < Safari 13.1
• In result I'll end up with build unable to run in browsers with lower versions than specified above

With this feature I would like to be able to identify non-es5 dependencies and list them in a way so they can be easily imported in babel config, so babel will transpile them. I think listing package names is good enough, it can be used then to generate regex easily.

Why Is This Update Needed?

To automate node builds.

If I run es-check in my project, with is a module with "package.json", I would expect to execute es-check for each dependency (and their nested dependencies), and list incompatible modules.

Are There Examples Of This Requested Update Elsewhere?

are-you-es5 unfortunately packages can't detect es2022, probably due to no updates since 2 years

Alternative to glob

Requested Update

Ditch glob

Why Is This Update Needed?

• Every (sub)dependency is a potential vulnerable security risk 78% of vulnerabilities are found in indirect dependencies
• There is a built in option to list files recursively.
• And even without it, it could be very easy to implement a async iterator to do it
• the native option is probably way faster
• reduce dependencies / size
• this are all the things you include by using glob

Are There Examples Of This Requested Update Elsewhere?

import { readdir } from 'node:fs/promises'

const files = await readdir(path, { recursive: true })

for (const file of files)
  console.log(file)

Since it's relative new, a own approch to this would be to just do:

import { opendir } from 'node:fs/promises'
import { join } from 'node:path'

/** @parma {string} path */
async function* readdir(path) {
  const dir = await opendir(path)
  for await (const dirent of dir) {
    const name = join(path, dirent.name)
    if (dirent.isDirectory()) {
      yield* listDir(name)
    } else {
      yield name
    }
  }
}

const files = await readdir(path)

for (const file of files)
  console.log(file)

This solution is probably way faster than any gulp alternative
and to provide more fine gradient filter create some default filter- generator

async function * match (iterable) {
  for await (const file of iterable)
    if (!file.include('node_module') && file.endsWith('.js')) yield file
}

for await (const file of match( readdir(path) )) {
  esCheck(path)
}

it dose not really need to be any fancy glob syntax

Read about references issues here. Provide paragraph text responses to each header.

Update copyright in `LICENSE`

Requested Update

This is more of a note that the LICENSE still attributes copyright to Dollar Shave Club as of 2017 and you might want to update it with a new line indicating the ownership lineage.

Why Is This Update Needed?

Generally ideal to keep the license and copyright up to date.

Are There Examples Of This Requested Update Elsewhere?

https://github.com/orgs/community/discussions/47161

If there's a sourcemap for a file, mention the original line that causes the error

Currently if I run es-check for a bundled/minified filed, it's a bit hard to tell which exact line of code (and which related library/file) causes the error. See screen below.

Instead, we could consume sourcemap (if there's one located in the file or next to it, e.g. a.js and a.js.map) with https://www.npmjs.com/package/source-map#new-sourcemapconsumerrawsourcemap , and then improve the es-check error message, by saying what's the original line that causes the error.

What do you think? Would you be open to such a code contribution?

Update acorn to latest version

When running es-check over my production build, I get this error:

          ES-Check Error:
          ----
          · erroring file: ./build/vendor-495a726ca52bcd7d3511.js
          · error: SyntaxError: Parenthesized pattern (124:4651)
          · see the printed err.stack below for context
          ----

          SyntaxError: Parenthesized pattern (124:4651)

It seems this might be a bug in the older version of acorn. Is it possible for es-check to use the latest version instead please?

[Request] Node API

Requested Update

Right now the only way to make the ES check is to use the command line.
This proposal is to also have the possibility to consume it from without node (as a function) - without spawning a child process to execute the command.

Why Is This Update Needed?

Many FE build tools are written in Node, and having an API to do the ES check would be great. It would be faster than spawning a process, error handling could be fine-tuned.
This is seen in many places - i.e: webpack or babel do it.

Feasibility

Looking at the main file, it should be easy to split it in 2 (the command line part and the actual processing)
I'll be happy to open a PR if the proposal gets a go-ahead

Are There Examples Of This Requested Update Elsewhere?

Read about references issues here. Provide paragraph text responses to each header.

es-check es5 does not catch Promise, Map, Set etc.

I was asked today if there was a tool to check if the transpiled code was ES5 and I referred to this project but I just checked and es-check es5 ... does not catch Promise from ES2015.

Some action needed to update the vulnerable `ansi-regex` package

Requested Update

A vulnerability was discovered in the ansi-regex package a few days ago.
GitHub Advisory Database: GHSA-93q8-gq69-wqmw

This package is an indirect dependency in the tree:

es-check@^6.0.0
  > caporal@^1.4.0
    > tabtab@^2.2.2
      > inquirer@^1.0.2
        > chalk@^1.0.0
          > strip-ansi@^3.0.0
            > ansi-regex@^2.0.0
          > has-ansi@^2.0.0
            > ansi-regex@^2.0.0

So this vulnerable dependency came from the caporal package. But unfortunately looks like caporal is no longer supported for a long time - the last commit was in June 2020, and there is no activity in Issues and PRs.

Do you see any option for solving this security-related problem? Perhaps caporal can be replaced with some other package?

Why Is This Update Needed?

Because there is a vulnerability in the indirect dependency ansi-regex@^2.0.0

Are There Examples Of This Requested Update Elsewhere?

No

Read about references issues here. Provide paragraph text responses to each header.

ES3/ES5 Object.assign not reported.

es-check es3 ./src/*.js

does not report Object.assign (ES6).

"es-check": "^5.2.3"

Failure to apply `not` option in .escheckrc

Requested Update

Update logic when falling back to not option in .escheckrc

Why Is This Update Needed?

Currently the not option isn't applied.

Are There Examples Of This Requested Update Elsewhere?

No

Misc

Caporal returns [] by default since the prog.LIST validator is used. This means options.not is never falsy and will not use config.not.

Is there any way to skip checking to a specific keyword?

Hi, Is there any way to skip checking to a specific keyword?
I support only IE11. so specific keyword like const is ES6 syntax but, It is fully supported by IE11.

so when I check the version of es5, I want to pass the task even if const exists.
Is there any way for this?

Thanks in advance.