es-check 9.1.5-0 → 9.2.0

package/README.md

@@ -99,16 +99,12 @@ The images below demonstrate command line scripts and their corresponding logged
 
 ![fail](https://user-images.githubusercontent.com/1074042/31471486-d65c3a80-ae9d-11e7-94fd-68b7acdb2d89.jpg)
 
-**ES Check** is run above with node commands. It can also be run within npm scripts, ci tools, or testing suites.
+**ES Check** is run above with node commands. It can also be run within npm scripts, ci tools, or testing suites. It also provide minimal support for use in node apps. 
 
 ---
 
 ## API
 
-**ES Check** provides the necessities. It accepts its place as a JavaScript matcher/tester.
-
-### General Information
-
 ```sh
 
 # USAGE
@@ -156,6 +152,7 @@ Here's a comprehensive list of all available options:
 | `--browserslistPath <path>` | Path to custom browserslist configuration (default: uses standard browserslist config resolution) |
 | `--browserslistEnv <env>` | Browserslist environment to use (default: production) |
 | `--config <path>` | Path to custom .escheckrc config file |
+| `--batchSize <number>` | Number of files to process concurrently (0 for unlimited, default: 0) |
 | `-h, --help` | Display help for command |
 
 ### Shell Completion
@@ -275,7 +272,7 @@ es-check checkBrowser ./dist/**/*.js
 
 ## Usage
 
-ES Check is a shell command CLI. It is run in [shell tool](http://linuxcommand.org/lc3_learning_the_shell.php) like Terminal, ITerm, or Hyper. It takes in two arguments: an [ECMAScript version](https://www.w3schools.com/js/js_versions.asp) (`<ECMAScript version>`) and files (`[files]`) in [globs](http://searchsecurity.techtarget.com/definition/globbing).
+ES Check is mainly a shell command CLI. It is run in [shell tool](http://linuxcommand.org/lc3_learning_the_shell.php) like Terminal, ITerm, or Hyper. It takes in two arguments: an [ECMAScript version](https://www.w3schools.com/js/js_versions.asp) (`<ECMAScript version>`) and files (`[files]`) in [globs](http://searchsecurity.techtarget.com/definition/globbing).
 
 Here are some example of **es check** scripts that could be run:
 
@@ -287,6 +284,36 @@ es-check es6 ./js/*.js
 es-check es6 ./js/*.js ./dist/*.js
 ```
 
+### Using ES Check in Node
+
+In addition to its CLI utility, ES Check can be used programmatically in Node.js applications:
+
+```javascript
+const { runChecks, loadConfig } = require('es-check');
+
+async function checkMyFiles() {
+  const config = {
+    ecmaVersion: 'es5',
+    files: ['dist/**/*.js'],
+    module: false,
+    checkFeatures: true
+  };
+  
+  try {
+    await runChecks([config], logger);
+    console.log('All files passed ES5 check!');
+  } catch (error) {
+    console.error('Some files failed the ES check');
+    process.exit(1);
+  }
+}
+
+async function checkWithConfig() {
+  const configs = await loadConfig('./.escheckrc');
+  await runChecks(configs, logger);
+}
+```
+
 ---
 
 ## Configuration
@@ -496,6 +523,40 @@ es-check --checkBrowser --checkFeatures ./dist/**/*.js
 
 ---
 
+## Performance Optimization
+
+ES Check provides the `--batchSize` option to optimize performance for different scenarios:
+
+```sh
+# Process all files in parallel (default)
+es-check es5 './dist/**/*.js' --batchSize 0
+
+# Process 10 files at a time (memory-constrained environments)
+es-check es5 './dist/**/*.js' --batchSize 10
+
+# Process 50 files at a time (balanced approach)
+es-check es5 './dist/**/*.js' --batchSize 50
+```
+
+### Performance Guidelines
+
+| Scenario | Recommended `--batchSize` | Reason |
+|----------|---------------------------|---------|
+| Small codebases (< 100 files) | `0` (unlimited) | Maximum parallelism for fastest results |
+| Medium codebases (100-500 files) | `0` or `50` | Balance between speed and memory |
+| Large codebases (> 500 files) | `50-100` | Prevent memory spikes |
+| CI/CD with limited memory | `10-20` | Conservative memory usage |
+| Local development | `0` (default) | Utilize available hardware |
+
+### Recent Performance Improvements
+
+As of August 2025, ES Check has been optimized with:
+- **Single-parse optimization**: Files are parsed once and the AST is reused
+- **Async file processing**: Non-blocking I/O for better performance
+- **Configurable batch processing**: Fine-tune based on your needs
+
+---
+
 ## Checking node_modules Dependencies
 
 To check node_modules dependencies for ES compatibility:
@@ -514,13 +575,13 @@ A simple example script is available in `examples/check-node-modules.js`.
 
 ## Acknowledgements
 
-ES Check is a small utility using powerful tools that [Isaac Z. Schlueter](https://github.com/isaacs), [Marijn Haverbeke](https://github.com/marijnh), and [Matthias Etienne](https://github.com/mattallty) built. [ES Checker](https://github.com/ruanyf/es-checker) by [Ruan YiFeng](https://github.com/ruanyf) checks the JavaScript version supported within a [browser](http://ruanyf.github.io/es-checker/) 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](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/) about [deploying es2015 code to production today] by [Philip Walton](https://github.com/philipwalton).
+ES Check is a small utility using powerful tools that [Isaac Z. Schlueter](https://github.com/isaacs), [Marijn Haverbeke](https://github.com/marijnh), and [Matthias Etienne](https://github.com/mattallty) built. [ES Checker](https://github.com/ruanyf/es-checker) by [Ruan YiFeng](https://github.com/ruanyf) checks the JavaScript version supported within a [browser](http://ruanyf.github.io/es-checker/) 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 [Philip Walton](https://github.com/philipwalton)'s post about [deploying es2015 code to production today](https://philipwalton.com/articles/deploying-es2015-code-in-production-today/).
 
 ---
 
 ## Contributing
 
-ES Check has 7 dependencies: [acorn and acorn-walk](https://github.com/ternjs/acorn/), [fast-glob](https://github.com/mrmlnc/fast-glob), [supports-color](github.com/chalk/supports-color), [winston](https://github.com/winstonjs/winston), [browserslist](https://github.com/browserslist/browserslist), and [commander](https://github.com/tj/commander). To contribute, file an [issue](https://github.com/yowainwright/es-check/issues) or submit a pull request.
+ES Check has 7 dependencies: [acorn and acorn-walk](https://github.com/ternjs/acorn/), [fast-glob](https://github.com/mrmlnc/fast-glob), [supports-color](https://github.com/chalk/supports-color), [winston](https://github.com/winstonjs/winston), [browserslist](https://github.com/browserslist/browserslist), and [commander](https://github.com/tj/commander). To contribute, file an [issue](https://github.com/yowainwright/es-check/issues) or submit a pull request.
 
 To update es versions, check out these lines of code [here](https://github.com/yowainwright/es-check/blob/main/index.js#L92-L153) and [here (in acorn.js)](https://github.com/acornjs/acorn/blob/3221fa54f9dea30338228b97210c4f1fd332652d/acorn/src/acorn.d.ts#L586).
 

package/detectFeatures.js

@@ -29,12 +29,12 @@ const detectPolyfills = (
 }
 
 const detectFeatures = (code, ecmaVersion, sourceType, ignoreList = new Set(), options = {}) => {
-  const { checkForPolyfills } = options;
+  const { checkForPolyfills, ast: providedAst } = options;
 
   const polyfills = new Set();
   if (checkForPolyfills) detectPolyfills(code, polyfills);
 
-  const ast = acorn.parse(code, {
+  const ast = providedAst || acorn.parse(code, {
     ecmaVersion: 'latest',
     sourceType,
   });

package/index.js

@@ -11,7 +11,7 @@ let polyfillDetector = null;
 const pkg = require('./package.json')
 const { lilconfig } = require('lilconfig');
 const { JS_VERSIONS } = require('./constants');
-const { parseIgnoreList, createLogger, generateBashCompletion, generateZshCompletion } = require('./utils');
+const { parseIgnoreList, createLogger, generateBashCompletion, generateZshCompletion, processBatchedFiles, readFileAsync, parseCode } = require('./utils');
 
 program.configureOutput({
   writeOut: (str) => process.stdout.write(str),
@@ -98,6 +98,7 @@ program
   .option('--browserslistPath <path>', 'path to custom browserslist configuration')
   .option('--browserslistEnv <env>', 'browserslist environment to use')
   .option('--config <path>', 'path to custom .escheckrc config file')
+  .option('--batchSize <number>', 'number of files to process concurrently (0 for unlimited)', '0')
 
 async function loadConfig(customConfigPath) {
   const logger = createLogger();
@@ -178,6 +179,7 @@ program
         browserslistQuery: options.browserslistQuery !== undefined ? options.browserslistQuery : baseConfig.browserslistQuery,
         browserslistPath: options.browserslistPath !== undefined ? options.browserslistPath : baseConfig.browserslistPath,
         browserslistEnv: options.browserslistEnv !== undefined ? options.browserslistEnv : baseConfig.browserslistEnv,
+        batchSize: options.batchSize !== undefined ? options.batchSize : baseConfig.batchSize,
       };
 
       if (ecmaVersionArg !== undefined) {
@@ -367,20 +369,22 @@ async function runChecks(configs, logger) {
       }
     }
 
-    const expandedPathsToIgnore = pathsToIgnore.reduce((result, path) =>
-      path.includes('*') ? result.concat(glob.sync(path, globOpts)) : result.concat(path)
-    , [])
-
-    const filterForIgnore = (globbedFiles) => {
-      if (expandedPathsToIgnore && expandedPathsToIgnore.length > 0) {
-        return globbedFiles.filter(
-          (filePath) => !expandedPathsToIgnore.some((ignoreValue) => filePath.includes(ignoreValue))
-        );
-      }
-      return globbedFiles;
+    let expandedPathsToIgnore = [];
+    if (pathsToIgnore.length > 0) {
+      expandedPathsToIgnore = pathsToIgnore.reduce((result, path) => {
+        if (path.includes('*')) {
+          return result.concat(glob.sync(path, globOpts));
+        }
+        return result.concat(path);
+      }, []);
     }
 
-    const filteredFiles = filterForIgnore(allMatchedFiles)
+    let filteredFiles = allMatchedFiles;
+    if (expandedPathsToIgnore.length > 0) {
+      filteredFiles = allMatchedFiles.filter((filePath) => {
+        return !expandedPathsToIgnore.some((ignoreValue) => filePath.includes(ignoreValue));
+      });
+    }
 
     const ignoreList = parseIgnoreList(config);
 
@@ -388,27 +392,27 @@ async function runChecks(configs, logger) {
       logger.debug('ES-Check: ignoring features:', Array.from(ignoreList).join(', '));
     }
 
-    filteredFiles.forEach((file) => {
-      const code = fs.readFileSync(file, 'utf8')
+    const batchSize = parseInt(config.batchSize || '0', 10);
+    
+    const processFile = async (file) => {
+      const { content: code, error: readError } = await readFileAsync(file, fs);
+      if (readError) {
+        return readError;
+      }
+
       if (logger.isLevelEnabled('debug')) {
         logger.debug(`ES-Check: checking ${file}`)
       }
-      try {
-        acorn.parse(code, acornOpts)
-      } catch (err) {
+
+      const { ast, error: parseError } = parseCode(code, acornOpts, acorn, file);
+      if (parseError) {
         if (logger.isLevelEnabled('debug')) {
-          logger.debug(`ES-Check: failed to parse file: ${file} \n - error: ${err}`)
-        }
-        const errorObj = {
-          err,
-          stack: err.stack,
-          file,
+          logger.debug(`ES-Check: failed to parse file: ${file} \n - error: ${parseError.err}`)
         }
-        errArray.push(errorObj);
-        return;
+        return parseError;
       }
 
-      if (!checkFeatures) return;
+      if (!checkFeatures) return null;
       const parseSourceType = acornOpts.sourceType || 'script';
       const esVersion = parseInt(ecmaVersion, 10);
 
@@ -416,7 +420,8 @@ async function runChecks(configs, logger) {
         code,
         esVersion,
         parseSourceType,
-        ignoreList
+        ignoreList,
+        { ast, checkForPolyfills }
       );
 
       if (logger.isLevelEnabled('debug')) {
@@ -442,13 +447,18 @@ async function runChecks(configs, logger) {
       const isSupported = filteredUnsupportedFeatures.length === 0;
       if (!isSupported) {
         const error = new Error(`Unsupported features used: ${filteredUnsupportedFeatures.join(', ')} but your target is ES${ecmaVersion}.`);
-        errArray.push({
+        return {
           err: error,
           file,
           stack: error.stack
-        });
+        };
       }
-    })
+      return null;
+    };
+
+    const results = await processBatchedFiles(filteredFiles, processFile, batchSize);
+    const errors = results.filter(result => result !== null);
+    errArray.push(...errors);
 
     if (errArray.length > 0) {
       logger.error(`ES-Check: there were ${errArray.length} ES version matching errors.`)
@@ -475,4 +485,11 @@ async function runChecks(configs, logger) {
   }
 }
 
-program.parse()
+if (require.main === module) {
+  program.parse()
+}
+
+module.exports = {
+  runChecks,
+  loadConfig
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "es-check",
-  "version": "9.1.5-0",
+  "version": "9.2.0",
   "description": "Checks the ECMAScript version of .js glob against a specified version of ECMAScript with a shell command",
   "main": "index.js",
   "license": "MIT",
@@ -18,6 +18,7 @@
   "scripts": {
     "commit": "git-cz",
     "commit-msg": "commitlint --edit $1",
+    "dev": "pnpm site:dev",
     "lint": "eslint index.js --fix",
     "lint:ci": "eslint index.js utils.js detectFeatures.js constants.js browserslist.js polyfillDetector.js",
     "pre-commit": "pnpm lint && pnpm test",
@@ -28,7 +29,11 @@
     "setup": "pnpm install --reporter=silent",
     "test": "nyc mocha test.js utils.test.js browserslist.test.js polyfillDetector.test.js detectFeatures.test.js --timeout 10s",
     "update": "codependence --update",
-    "benchmark": "./benchmarks/run-benchmarks.sh"
+    "benchmark": "./benchmarks/run-benchmarks.sh",
+    "site:dev": "pnpm --filter es-check-docs run dev",
+    "site:build": "pnpm --filter es-check-docs run build",
+    "site:preview": "pnpm --filter es-check-docs run preview",
+    "site:install": "pnpm --filter es-check-docs install"
   },
   "repository": {
     "type": "git",
@@ -52,8 +57,8 @@
     "codependence": "^0.3.1",
     "commitizen": "4.3.1",
     "conventional-changelog-cli": "^5.0.0",
-    "eslint": "9.30.0",
-    "eslint-config-prettier": "10.1.5",
+    "eslint": "9.32.0",
+    "eslint-config-prettier": "10.1.8",
     "eslint-plugin-es5": "^1.5.0",
     "husky": "9.1.7",
     "is-ci": "^3.0.1",
@@ -61,7 +66,7 @@
     "nyc": "^17.1.0",
     "path-exists-cli": "^2.0.0",
     "prettier": "3.6.2",
-    "release-it": "19.0.3"
+    "release-it": "19.0.4"
   },
   "dependencies": {
     "acorn": "8.15.0",

package/utils.js

@@ -338,6 +338,75 @@ _${cmdName.replace(/-/g, '_')}
 `;
 }
 
+/**
+ * Process files in batches for better performance
+ * @param {string[]} files - Array of file paths to process
+ * @param {Function} processor - Async function to process each file
+ * @param {number} batchSize - Number of files to process concurrently (0 for unlimited)
+ * @returns {Promise<Array>} Array of results from processing all files
+ */
+async function processBatchedFiles(files, processor, batchSize = 0) {
+  if (batchSize <= 0) {
+    return Promise.all(files.map(processor));
+  }
+  
+  const results = [];
+  
+  for (let i = 0; i < files.length; i += batchSize) {
+    const batch = files.slice(i, i + batchSize);
+    const batchResults = await Promise.all(batch.map(processor));
+    results.push(...batchResults);
+  }
+  
+  return results;
+}
+
+/**
+ * Read file asynchronously with error handling
+ * @param {string} file - File path to read
+ * @param {Object} fs - File system module
+ * @returns {Promise<{content: string, error: null} | {content: null, error: Object}>}
+ */
+async function readFileAsync(file, fs) {
+  try {
+    const content = await fs.promises.readFile(file, 'utf8');
+    return { content, error: null };
+  } catch (err) {
+    return { 
+      content: null, 
+      error: {
+        err,
+        file,
+        stack: err.stack
+      }
+    };
+  }
+}
+
+/**
+ * Parse code with acorn and handle errors
+ * @param {string} code - Code to parse
+ * @param {Object} acornOpts - Acorn parsing options
+ * @param {Object} acorn - Acorn module
+ * @param {string} file - File path for error reporting
+ * @returns {{ast: Object, error: null} | {ast: null, error: Object}}
+ */
+function parseCode(code, acornOpts, acorn, file) {
+  try {
+    const ast = acorn.parse(code, acornOpts);
+    return { ast, error: null };
+  } catch (err) {
+    return {
+      ast: null,
+      error: {
+        err,
+        stack: err.stack,
+        file
+      }
+    };
+  }
+}
+
 module.exports = {
   parseIgnoreList,
   checkVarKindMatch,
@@ -347,5 +416,8 @@ module.exports = {
   checkMap,
   createLogger,
   generateBashCompletion,
-  generateZshCompletion
+  generateZshCompletion,
+  processBatchedFiles,
+  readFileAsync,
+  parseCode
 };