es-check 9.2.0 → 9.3.0

package/README.md

@@ -153,6 +153,7 @@ Here's a comprehensive list of all available options:
 | `--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) |
+| `--noCache` | Disable file caching (cache is enabled by default) |
 | `-h, --help` | Display help for command |
 
 ### Shell Completion
@@ -203,7 +204,7 @@ es-check es6 './dist/**/*.js' --module
 **Checking files with hash bang:**
 
 ```sh
-es-check es6 './bin/*.js' --allowHashBang
+es-check es6 './tests/*.js' --allowHashBang
 ```
 
 **Skipping specific files or directories:**
@@ -284,7 +285,7 @@ es-check es6 ./js/*.js
 es-check es6 ./js/*.js ./dist/*.js
 ```
 
-### Using ES Check in Node
+### Using ES Check in Node (Programmatic API)
 
 In addition to its CLI utility, ES Check can be used programmatically in Node.js applications:
 
@@ -292,25 +293,30 @@ In addition to its CLI utility, ES Check can be used programmatically in Node.js
 const { runChecks, loadConfig } = require('es-check');
 
 async function checkMyFiles() {
-  const config = {
+  const configs = [{
     ecmaVersion: 'es5',
     files: ['dist/**/*.js'],
     module: false,
     checkFeatures: true
-  };
+  }];
   
-  try {
-    await runChecks([config], logger);
+  const result = await runChecks(configs);
+  
+  if (result.success) {
     console.log('All files passed ES5 check!');
-  } catch (error) {
-    console.error('Some files failed the ES check');
-    process.exit(1);
+    // Output: All files passed ES5 check!
+  } else {
+    console.error(`ES Check failed with ${result.errors.length} errors`);
+    result.errors.forEach(error => {
+      console.error(`- ${error.file}: ${error.err.message}`);
+    });
+    // Example output:
+    // ES Check failed with 2 errors
+    // - dist/app.js: Unsupported features used: const, arrow-functions but your target is ES5.
+    // - dist/utils.js: Unsupported features used: template-literals but your target is ES5.
   }
-}
-
-async function checkWithConfig() {
-  const configs = await loadConfig('./.escheckrc');
-  await runChecks(configs, logger);
+  
+  return result;
 }
 ```
 
@@ -525,7 +531,26 @@ es-check --checkBrowser --checkFeatures ./dist/**/*.js
 
 ## Performance Optimization
 
-ES Check provides the `--batchSize` option to optimize performance for different scenarios:
+ES Check includes several performance optimizations:
+
+### File Caching
+File caching is **enabled by default** for faster re-checking:
+
+```sh
+# Cache is enabled by default
+es-check es5 './dist/**/*.js'
+
+# Disable cache if needed
+es-check es5 './dist/**/*.js' --noCache
+```
+
+We observed ~28% performance improvement in our [benchmark tests](./benchmarks/README.md). Your results may vary based on file sizes and system configuration. Try the benchmarks yourself:
+```sh
+node benchmarks/compare-tools.js 3 ./benchmarks/test-files
+```
+
+### Batch Processing
+The `--batchSize` option optimizes memory usage:
 
 ```sh
 # Process all files in parallel (default)

package/esm-wrapper.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const esCheck = require('./index.js');
+
+export const { runChecks, loadConfig, createLogger } = esCheck;
+export default esCheck;

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, processBatchedFiles, readFileAsync, parseCode } = require('./utils');
+const { parseIgnoreList, createLogger, generateBashCompletion, generateZshCompletion, processBatchedFiles, readFileAsync, clearFileCache, getFileCacheStats, parseCode, determineInvocationType, determineLogLevel, handleESVersionError } = require('./utils');
 
 program.configureOutput({
   writeOut: (str) => process.stdout.write(str),
@@ -99,6 +99,7 @@ program
   .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')
+  .option('--noCache', 'disable file caching (caching is enabled by default)', false)
 
 async function loadConfig(customConfigPath) {
   const logger = createLogger();
@@ -180,6 +181,7 @@ program
         browserslistPath: options.browserslistPath !== undefined ? options.browserslistPath : baseConfig.browserslistPath,
         browserslistEnv: options.browserslistEnv !== undefined ? options.browserslistEnv : baseConfig.browserslistEnv,
         batchSize: options.batchSize !== undefined ? options.batchSize : baseConfig.batchSize,
+        cache: options.noCache ? false : (baseConfig.cache !== undefined ? baseConfig.cache : true),
       };
 
       if (ecmaVersionArg !== undefined) {
@@ -203,8 +205,17 @@ program
     return runChecks(configs, logger);
   })
 
-async function runChecks(configs, logger) {
+async function runChecks(configs, loggerOrOptions) {
+  const { isNodeAPI, logger } = determineInvocationType(loggerOrOptions);
+  
+  const logLevels = determineLogLevel(logger);
+  const isDebug = logLevels?.isDebug || false;
+  const isWarn = logLevels?.isWarn || false;
+  const isInfo = logLevels?.isInfo || false;
+  const isError = logLevels?.isError || false;
+  
   let hasErrors = false;
+  const allErrors = [];
 
   for (const config of configs) {
     const expectedEcmaVersion = config.ecmaVersion;
@@ -227,47 +238,88 @@ async function runChecks(configs, logger) {
     const checkBrowser = config.checkBrowser;
     const ignoreFilePath = config.ignoreFile || config['ignore-file'];
 
-    if (ignoreFilePath && !fs.existsSync(ignoreFilePath) && logger.isLevelEnabled('warn')) {
+    const ignoreFileExists = ignoreFilePath && fs.existsSync(ignoreFilePath);
+    const shouldWarnAboutIgnoreFile = ignoreFilePath && !ignoreFileExists && isWarn;
+    if (shouldWarnAboutIgnoreFile) {
       logger.warn(`Warning: Ignore file '${ignoreFilePath}' does not exist or is not accessible`);
     }
 
-    if (!expectedEcmaVersion && !config.checkBrowser) {
-      logger.error('No ecmaScript version or checkBrowser option specified in configuration');
-      process.exit(1);
+    const hasEcmaVersion = Boolean(expectedEcmaVersion);
+    const hasBrowserCheck = Boolean(config.checkBrowser);
+    const missingVersionSpecification = !hasEcmaVersion && !hasBrowserCheck;
+    
+    if (missingVersionSpecification) {
+      if (logger) logger.error('No ecmaScript version or checkBrowser option specified in configuration');
+      if (!isNodeAPI) {
+        process.exit(1);
+      } else {
+        allErrors.push({ err: new Error('No ecmaScript version or checkBrowser option specified in configuration'), file: 'config' });
+        hasErrors = true;
+        continue;
+      }
     }
 
-    if (looseGlobMatching && logger.isLevelEnabled('debug')) {
+    if (looseGlobMatching && isDebug) {
       logger.debug('ES-Check: loose-glob-matching is set');
     }
 
     const globOpts = { nodir: true }
     let allMatchedFiles = [];
-    if (patternsToGlob.length === 0 && !looseGlobMatching) {
-        logger.error('ES-Check: No file patterns specified to check.');
-        process.exit(1);
+    
+    const hasFilePatterns = patternsToGlob.length > 0;
+    const shouldEnforceFilePatterns = !hasFilePatterns && !looseGlobMatching;
+    
+    if (shouldEnforceFilePatterns) {
+        if (logger) logger.error('ES-Check: No file patterns specified to check.');
+        if (!isNodeAPI) {
+          process.exit(1);
+        } else {
+          allErrors.push({ err: new Error('No file patterns specified to check'), file: 'config' });
+          hasErrors = true;
+          continue;
+        }
     }
 
     patternsToGlob.forEach((pattern) => {
       const globbedFiles = glob.sync(pattern, globOpts);
-      if (globbedFiles.length === 0 && !looseGlobMatching) {
-        logger.error(`ES-Check: Did not find any files to check for pattern: ${pattern}.`);
-        process.exit(1);
+      const noFilesFound = globbedFiles.length === 0;
+      const shouldErrorOnNoFiles = noFilesFound && !looseGlobMatching;
+      
+      if (shouldErrorOnNoFiles) {
+        if (logger) logger.error(`ES-Check: Did not find any files to check for pattern: ${pattern}.`);
+        if (!isNodeAPI) {
+          process.exit(1);
+        } else {
+          allErrors.push({ err: new Error(`Did not find any files to check for pattern: ${pattern}`), file: 'glob' });
+          hasErrors = true;
+        }
       }
       allMatchedFiles = allMatchedFiles.concat(globbedFiles);
     });
 
-    if (allMatchedFiles.length === 0) {
-      if (patternsToGlob.length > 0) {
-        logger.error(`ES-Check: Did not find any files to check across all patterns: ${patternsToGlob.join(', ')}.`);
-        process.exit(1);
-      } else if (looseGlobMatching) {
-        logger.warn('ES-Check: No file patterns specified or no files found (running in loose mode).');
+    const noMatchedFiles = allMatchedFiles.length === 0;
+    const shouldErrorOnNoMatchedFiles = noMatchedFiles && hasFilePatterns && !looseGlobMatching;
+    const shouldWarnOnNoMatchedFiles = noMatchedFiles && looseGlobMatching;
+    
+    if (noMatchedFiles) {
+      if (shouldErrorOnNoMatchedFiles) {
+        if (logger) logger.error(`ES-Check: Did not find any files to check across all patterns: ${patternsToGlob.join(', ')}.`);
+        if (!isNodeAPI) {
+          process.exit(1);
+        } else {
+          allErrors.push({ err: new Error(`Did not find any files to check across all patterns: ${patternsToGlob.join(', ')}`), file: 'glob' });
+          hasErrors = true;
+          continue;
+        }
+      } else if (shouldWarnOnNoMatchedFiles) {
+        if (logger) logger.warn('ES-Check: No file patterns specified or no files found (running in loose mode).');
       }
     }
 
     let ecmaVersion
 
     const isBrowserslistCheck = Boolean(expectedEcmaVersion === 'checkBrowser' || checkBrowser !== undefined);
+    
     if (isBrowserslistCheck) {
       const browserslistQuery = config.browserslistQuery;
       try {
@@ -280,12 +332,18 @@ async function runChecks(configs, logger) {
 
         ecmaVersion = esVersionFromBrowserslist.toString();
 
-        if (logger.isLevelEnabled('debug')) {
+        if (isDebug) {
           logger.debug(`ES-Check: Using ES${ecmaVersion} based on browserslist configuration`);
         }
       } catch (err) {
-        logger.error(`Error determining ES version from browserslist: ${err.message}`);
-        process.exit(1);
+        if (logger) logger.error(`Error determining ES version from browserslist: ${err.message}`);
+        if (!isNodeAPI) {
+          process.exit(1);
+        } else {
+          allErrors.push({ err: new Error(`Error determining ES version from browserslist: ${err.message}`), file: 'browserslist' });
+          hasErrors = true;
+          continue;
+        }
       }
     } else {
       switch (expectedEcmaVersion) {
@@ -293,8 +351,14 @@ async function runChecks(configs, logger) {
         ecmaVersion = '3'
         break
       case 'es4':
-        logger.error('ES4 is not supported.')
-        process.exit(1)
+        if (logger) logger.error('ES4 is not supported.')
+        if (!isNodeAPI) {
+          process.exit(1)
+        } else {
+          allErrors.push({ err: new Error('ES4 is not supported'), file: 'config' });
+          hasErrors = true;
+          continue;
+        }
       case 'es5':
         ecmaVersion = '5'
         break
@@ -343,28 +407,34 @@ async function runChecks(configs, logger) {
         ecmaVersion = '16'
         break
       default:
-        logger.error('Invalid ecmaScript version, please pass a valid version, use --help for help')
-        process.exit(1)
+        if (logger) logger.error('Invalid ecmaScript version, please pass a valid version, use --help for help')
+        if (!isNodeAPI) {
+          process.exit(1)
+        } else {
+          allErrors.push({ err: new Error('Invalid ecmaScript version'), file: 'config' });
+          hasErrors = true;
+          continue;
+        }
       }
     }
 
     const errArray = []
     const acornOpts = { ecmaVersion: parseInt(ecmaVersion, 10), silent: true }
 
-    if (logger.isLevelEnabled('debug')) {
+    if (isDebug) {
       logger.debug(`ES-Check: Going to check files using version ${ecmaVersion}`)
     }
 
     if (esmodule) {
       acornOpts.sourceType = 'module'
-      if (logger.isLevelEnabled('debug')) {
+      if (isDebug) {
         logger.debug('ES-Check: esmodule is set')
       }
     }
 
     if (allowHashBang) {
       acornOpts.allowHashBang = true
-      if (logger.isLevelEnabled('debug')) {
+      if (isDebug) {
         logger.debug('ES-Check: allowHashBang is set')
       }
     }
@@ -388,25 +458,29 @@ async function runChecks(configs, logger) {
 
     const ignoreList = parseIgnoreList(config);
 
-    if (ignoreList.size > 0 && logger.isLevelEnabled('debug')) {
+    if (ignoreList.size > 0 && isDebug) {
       logger.debug('ES-Check: ignoring features:', Array.from(ignoreList).join(', '));
     }
 
     const batchSize = parseInt(config.batchSize || '0', 10);
     
     const processFile = async (file) => {
-      const { content: code, error: readError } = await readFileAsync(file, fs);
+      const useCache = config.cache !== false;
+      const { content: code, error: readError } = await readFileAsync(file, fs, useCache);
       if (readError) {
         return readError;
       }
 
-      if (logger.isLevelEnabled('debug')) {
+      if (isDebug) {
         logger.debug(`ES-Check: checking ${file}`)
       }
 
-      const { ast, error: parseError } = parseCode(code, acornOpts, acorn, file);
+      const needsFullAST = checkFeatures;
+      const parserOptions = needsFullAST ? acornOpts : { ...acornOpts, locations: false, ranges: false, onComment: null };
+      
+      const { ast, error: parseError } = parseCode(code, parserOptions, acorn, file);
       if (parseError) {
-        if (logger.isLevelEnabled('debug')) {
+        if (isDebug) {
           logger.debug(`ES-Check: failed to parse file: ${file} \n - error: ${parseError.err}`)
         }
         return parseError;
@@ -424,7 +498,7 @@ async function runChecks(configs, logger) {
         { ast, checkForPolyfills }
       );
 
-      if (logger.isLevelEnabled('debug')) {
+      if (isDebug) {
         const stringifiedFeatures = JSON.stringify(foundFeatures, null, 2);
         logger.debug(`Features found in ${file}: ${stringifiedFeatures}`);
       }
@@ -435,11 +509,11 @@ async function runChecks(configs, logger) {
           polyfillDetector = require('./polyfillDetector');
         }
 
-        const polyfills = polyfillDetector.detectPolyfills(code, logger);
+        const polyfills = polyfillDetector.detectPolyfills(code, logger || { debug: () => {}, isLevelEnabled: () => false });
 
         filteredUnsupportedFeatures = polyfillDetector.filterPolyfilled(unsupportedFeatures, polyfills);
 
-        if (logger.isLevelEnabled('debug') && filteredUnsupportedFeatures.length !== unsupportedFeatures.length) {
+        if (isDebug && filteredUnsupportedFeatures.length !== unsupportedFeatures.length) {
           logger.debug(`ES-Check: Polyfills reduced unsupported features from ${unsupportedFeatures.length} to ${filteredUnsupportedFeatures.length}`);
         }
       }
@@ -461,9 +535,11 @@ async function runChecks(configs, logger) {
     errArray.push(...errors);
 
     if (errArray.length > 0) {
-      logger.error(`ES-Check: there were ${errArray.length} ES version matching errors.`)
-      errArray.forEach((o) => {
-        logger.info(`
+      allErrors.push(...errArray);
+      if (logger) {
+        logger.error(`ES-Check: there were ${errArray.length} ES version matching errors.`)
+        errArray.forEach((o) => {
+          logger.info(`
           ES-Check Error:
           ----
           · erroring file: ${o.file}
@@ -472,16 +548,29 @@ async function runChecks(configs, logger) {
           ----\n
           ${o.stack}
         `)
-      })
+        })
+      }
       hasErrors = true;
-      process.exit(1)
-      return;
+      
+      if (!isNodeAPI) {
+        process.exit(1)
+        return;
+      }
+    } else {
+      if (logger) logger.info(`ES-Check: there were no ES version matching errors!  🎉`)
     }
-    logger.info(`ES-Check: there were no ES version matching errors!  🎉`)
   }
 
   if (hasErrors) {
-    process.exit(1);
+    if (!isNodeAPI) {
+      process.exit(1);
+    } else {
+      return { success: false, errors: allErrors };
+    }
+  }
+  
+  if (isNodeAPI) {
+    return { success: true, errors: [] };
   }
 }
 
@@ -491,5 +580,7 @@ if (require.main === module) {
 
 module.exports = {
   runChecks,
-  loadConfig
+  loadConfig,
+  // Export commonly used utilities
+  createLogger
 }

package/package.json

@@ -1,16 +1,23 @@
 {
   "name": "es-check",
-  "version": "9.2.0",
+  "version": "9.3.0",
   "description": "Checks the ECMAScript version of .js glob against a specified version of ECMAScript with a shell command",
   "main": "index.js",
   "license": "MIT",
+  "exports": {
+    ".": {
+      "import": "./esm-wrapper.mjs",
+      "require": "./index.js"
+    }
+  },
   "files": [
     "index.js",
     "utils.js",
     "detectFeatures.js",
     "constants.js",
     "browserslist.js",
-    "polyfillDetector.js"
+    "polyfillDetector.js",
+    "esm-wrapper.mjs"
   ],
   "bin": {
     "es-check": "index.js"
@@ -27,7 +34,10 @@
     "release": "release-it --no-git.requireUpstream",
     "report:coverage": "nyc report --reporter=lcov > coverage.lcov && codecov",
     "setup": "pnpm install --reporter=silent",
-    "test": "nyc mocha test.js utils.test.js browserslist.test.js polyfillDetector.test.js detectFeatures.test.js --timeout 10s",
+    "test": "nyc mocha test.js utils.test.js browserslist.test.js polyfillDetector.test.js detectFeatures.test.js --timeout 10s && npm run test:e2e",
+    "test:e2e": "npm run test:e2e:cli && npm run test:e2e:esm",
+    "test:e2e:cli": "node e2e/test-cli.js",
+    "test:e2e:esm": "node e2e/test-esm-import.mjs",
     "update": "codependence --update",
     "benchmark": "./benchmarks/run-benchmarks.sh",
     "site:dev": "pnpm --filter es-check-docs run dev",
@@ -57,7 +67,7 @@
     "codependence": "^0.3.1",
     "commitizen": "4.3.1",
     "conventional-changelog-cli": "^5.0.0",
-    "eslint": "9.32.0",
+    "eslint": "9.33.0",
     "eslint-config-prettier": "10.1.8",
     "eslint-plugin-es5": "^1.5.0",
     "husky": "9.1.7",

package/utils.js

@@ -361,18 +361,35 @@ async function processBatchedFiles(files, processor, batchSize = 0) {
   return results;
 }
 
+const SimpleCache = require('./cache');
+const fileCache = new SimpleCache(500, 60000);
+
 /**
  * Read file asynchronously with error handling
  * @param {string} file - File path to read
  * @param {Object} fs - File system module
+ * @param {boolean} useCache - Whether to use file cache (default: false)
  * @returns {Promise<{content: string, error: null} | {content: null, error: Object}>}
  */
-async function readFileAsync(file, fs) {
+async function readFileAsync(file, fs, useCache = false) {
+  if (useCache) {
+    const cached = fileCache.get(file);
+    if (cached !== undefined) {
+      return cached;
+    }
+  }
+  
   try {
     const content = await fs.promises.readFile(file, 'utf8');
-    return { content, error: null };
+    const result = { content, error: null };
+    
+    if (useCache) {
+      fileCache.set(file, result);
+    }
+    
+    return result;
   } catch (err) {
-    return { 
+    const result = { 
       content: null, 
       error: {
         err,
@@ -380,9 +397,29 @@ async function readFileAsync(file, fs) {
         stack: err.stack
       }
     };
+    
+    if (useCache) {
+      fileCache.set(file, result);
+    }
+    
+    return result;
   }
 }
 
+/**
+ * Clear the file cache
+ */
+function clearFileCache() {
+  fileCache.clear();
+}
+
+/**
+ * Get file cache statistics
+ */
+function getFileCacheStats() {
+  return fileCache.getStats();
+}
+
 /**
  * Parse code with acorn and handle errors
  * @param {string} code - Code to parse
@@ -407,6 +444,77 @@ function parseCode(code, acornOpts, acorn, file) {
   }
 }
 
+/**
+ * Determine how runChecks is being invoked (CLI vs Node API)
+ * @param {Object|null} loggerOrOptions - Logger or options object passed to runChecks
+ * @returns {{isNodeAPI: boolean, logger: Object|null}}
+ */
+function determineInvocationType(loggerOrOptions) {
+  let isNodeAPI = false;
+  let logger = null;
+  
+  if (!loggerOrOptions) {
+    isNodeAPI = true;
+    logger = null;
+  } else if (typeof loggerOrOptions === 'object' && !loggerOrOptions.info && !loggerOrOptions.error) {
+    isNodeAPI = true;
+    logger = loggerOrOptions.logger || null;
+  } else {
+    isNodeAPI = false;
+    logger = loggerOrOptions;
+  }
+  
+  return { isNodeAPI, logger };
+}
+
+/**
+ * Determine log levels based on logger capabilities
+ * @param {Object|null} logger - Logger object
+ * @returns {Object|null} Object with log level flags or null if no logger
+ */
+function determineLogLevel(logger) {
+  if (!logger || !logger.isLevelEnabled) {
+    return null;
+  }
+  
+  return {
+    isDebug: logger.isLevelEnabled('debug'),
+    isWarn: logger.isLevelEnabled('warn'),
+    isInfo: logger.isLevelEnabled('info'),
+    isError: logger.isLevelEnabled('error')
+  };
+}
+
+/**
+ * Handle ES version errors uniformly for different error types
+ * @param {Object} options - Options object
+ * @param {string} options.errorType - Type of error ('browserslist', 'es3', 'default')
+ * @param {string} options.errorMessage - Error message to display
+ * @param {Object|null} options.logger - Logger object
+ * @param {boolean} options.isNodeAPI - Whether running as Node API
+ * @param {Array} options.allErrors - Array to collect errors
+ * @param {string} [options.file='config'] - File reference for error
+ * @returns {{shouldContinue: boolean, hasErrors: boolean}}
+ */
+function handleESVersionError(options) {
+  const { errorType, errorMessage, logger, isNodeAPI, allErrors, file = 'config' } = options;
+  
+  if (logger) {
+    logger.error(errorMessage);
+  }
+  
+  if (!isNodeAPI) {
+    process.exit(1);
+    return { shouldContinue: false, hasErrors: true };
+  } else {
+    allErrors.push({ 
+      err: new Error(errorMessage), 
+      file 
+    });
+    return { shouldContinue: true, hasErrors: true };
+  }
+}
+
 module.exports = {
   parseIgnoreList,
   checkVarKindMatch,
@@ -419,5 +527,10 @@ module.exports = {
   generateZshCompletion,
   processBatchedFiles,
   readFileAsync,
-  parseCode
+  clearFileCache,
+  getFileCacheStats,
+  parseCode,
+  determineInvocationType,
+  determineLogLevel,
+  handleESVersionError
 };