es-check 9.7.2 → 9.8.0

package/README.md

@@ -140,13 +140,13 @@ Here's a comprehensive list of all available options:
 | `--quiet`                     | Quiet mode: only displays warn and error messages (default: false)                                                          |
 | `--looseGlobMatching`         | Doesn't fail if no files are found in some globs/files (default: false)                                                     |
 | `--silent`                    | Silent mode: does not output anything, giving no indication of success or failure other than the exit code (default: false) |
-| `--checkFeatures`             | Check for actual ES version specific features (default: false)                                                              |
+| `--checkFeatures`             | Check ES features; with `--checkBrowser`, also check support in target browsers (default: false)                            |
 | `--checkForPolyfills`         | Consider polyfills when checking features (only works with --checkFeatures) (default: false)                                |
 | `--ignorePolyfillable [lib]`  | Ignore polyfillable features; optionally specify library (e.g., `core-js`) to limit scope                                   |
 | `--ignore <features>`         | Comma-separated list of features to ignore, e.g., "ErrorCause,TopLevelAwait"                                                |
 | `--ignoreFile <path>`         | Path to JSON file containing features to ignore                                                                             |
 | `--allowList <features>`      | Comma-separated list of features to allow even in lower ES versions, e.g., "const,let"                                      |
-| `--checkBrowser`              | Use browserslist configuration to determine ES version (default: false)                                                     |
+| `--checkBrowser`              | Select an ES target from Browserslist; add `--checkFeatures` for per-browser feature checks (default: false)                |
 | `--browserslistQuery <query>` | Custom browserslist query (e.g., "last 2 versions")                                                                         |
 | `--browserslistPath <path>`   | Path to custom browserslist configuration (default: uses standard browserslist config resolution)                           |
 | `--browserslistEnv <env>`     | Browserslist environment to use (default: production)                                                                       |
@@ -229,6 +229,16 @@ es-check --checkBrowser --browserslistQuery="last 2 versions" ./dist/**/*.js
 es-check --checkBrowser --browserslistQuery=">0.5%, not dead" --checkFeatures ./dist/**/*.js
 ```
 
+When `--checkBrowser` is combined with `--checkFeatures`, every detected feature is also checked
+against the individual browser versions resolved from browserslist using
+[MDN browser-compat-data](https://github.com/mdn/browser-compat-data). For example
+`--browserslistQuery="ios_saf 15.0"` maps to ES2022, but `Object.hasOwn` and class static blocks are still
+reported because iOS Safari added them in 15.4 and 16.4. Failures name the browser that lacks support:
+
+```
+Unsupported features detected: ObjectHasOwn (safari_ios 15.0 requires 15.4). These require a higher ES version than 13 or are not supported by the target browsers.
+```
+
 **Using browserlist just like an es version**
 
 ```sh
@@ -332,12 +342,12 @@ Here's an example of what an `.escheckrc` file will look like:
 | `not`                | Array           | Files or glob patterns to exclude                                                    |
 | `allowHashBang`      | Boolean         | Whether to allow hash bang in files                                                  |
 | `looseGlobMatching`  | Boolean         | Whether to ignore missing files in globs                                             |
-| `checkFeatures`      | Boolean         | Whether to check for ES version specific features                                    |
+| `checkFeatures`      | Boolean         | Check ES features and, with `checkBrowser`, support in target browsers               |
 | `checkForPolyfills`  | Boolean         | Whether to consider polyfills when checking features                                 |
 | `ignorePolyfillable` | Boolean/String  | Ignore polyfillable features; set to library name (e.g., `"core-js"`) to limit scope |
 | `ignore`             | Array           | Features to ignore when checking                                                     |
 | `allowList`          | Array           | Features to allow even in lower ES versions                                          |
-| `checkBrowser`       | Boolean         | Whether to use browserslist configuration to determine ES version                    |
+| `checkBrowser`       | Boolean         | Select an ES target from Browserslist; use with `checkFeatures` for browser checks   |
 | `browserslistQuery`  | String          | Custom browserslist query to use                                                     |
 | `browserslistPath`   | String          | Path to custom browserslist configuration                                            |
 | `browserslistEnv`    | String          | Browserslist environment to use                                                      |
@@ -513,6 +523,8 @@ es-check --checkBrowser --browserslistEnv="production" ./dist/**/*.js
 
 **Combining with feature checking:**
 
+Add `--checkFeatures` to check detected features against individual target browser versions using MDN compatibility data, as well as the selected ES version:
+
 ```sh
 es-check --checkBrowser --checkFeatures ./dist/**/*.js
 ```

package/lib/browserslist.js

@@ -1,5 +1,16 @@
 const browserslist = require("browserslist");
-const { BROWSER_TO_ES_VERSION } = require("./constants/versions");
+const { BROWSER_TO_ES_VERSION, BROWSERSLIST_TO_BCD } = require("./constants/versions");
+
+const UNVERSIONED_BROWSER_VERSIONS = new Set(["all", "TP"]);
+
+function resolveBrowsers(options = {}) {
+  const { browserslistPath, browserslistEnv, browserslistQuery } = options;
+
+  return browserslist(browserslistQuery ?? null, {
+    config: browserslistPath,
+    env: browserslistEnv,
+  });
+}
 
 function getESVersionForBrowser(browser, version) {
   const defaultVersion = 5;
@@ -42,13 +53,10 @@ function getESVersionForBrowser(browser, version) {
 }
 
 function getESVersionFromBrowserslist(options = {}) {
-  const { browserslistPath, browserslistEnv, browserslistQuery } = options;
+  const { browserslistPath, browserslistEnv } = options;
 
   try {
-    const browsers = browserslist(browserslistQuery ?? null, {
-      config: browserslistPath,
-      env: browserslistEnv,
-    });
+    const browsers = resolveBrowsers(options);
 
     const hasNoBrowsers = !browsers || browsers.length === 0;
     if (hasNoBrowsers) {
@@ -99,7 +107,47 @@ function getESVersionFromBrowserslist(options = {}) {
   }
 }
 
+function parseBrowserVersion(version) {
+  const hasVersion = typeof version === "string" && version.length > 0;
+  if (!hasVersion) return null;
+
+  const lowerBound = version.split("-")[0];
+  const isUnversioned = UNVERSIONED_BROWSER_VERSIONS.has(lowerBound);
+  if (isUnversioned) return null;
+
+  return lowerBound;
+}
+
+function toTargetBrowser(entry) {
+  const [browserslistName, version] = entry.split(" ");
+  const name = BROWSERSLIST_TO_BCD[browserslistName];
+  const parsedVersion = parseBrowserVersion(version);
+
+  const isUnknownBrowser = !name;
+  const isUnknownVersion = parsedVersion === null;
+  const isUnknownTarget = isUnknownBrowser || isUnknownVersion;
+  if (isUnknownTarget) return null;
+
+  return { name, version: parsedVersion, browserslistName };
+}
+
+function getTargetBrowsers(options = {}) {
+  let browsers;
+
+  try {
+    browsers = resolveBrowsers(options);
+  } catch {
+    return [];
+  }
+
+  const hasNoBrowsers = !browsers || browsers.length === 0;
+  if (hasNoBrowsers) return [];
+
+  return browsers.map(toTargetBrowser).filter(Boolean);
+}
+
 module.exports = {
   getESVersionFromBrowserslist,
   getESVersionForBrowser,
+  getTargetBrowsers,
 };

package/lib/check-runner/index.js

@@ -78,7 +78,7 @@ function processConfig(config, context) {
     return { hasErrors: true, shouldContinue: true };
   }
 
-  const { ecmaVersion } = versionResult;
+  const { ecmaVersion, targetBrowsers } = versionResult;
   const useLatestForParsing = config.checkFeatures;
   const targetEsVersion = parseInt(ecmaVersion, 10);
 
@@ -130,6 +130,7 @@ function processConfig(config, context) {
     logger,
     isDebug,
     ecmaVersion,
+    targetBrowsers,
   });
 
   const results = processBatchedFiles(filteredFiles, processFile, batchSize);

package/lib/check-runner/utils.js

@@ -199,18 +199,20 @@ function determineEcmaVersion(config, options) {
   const isBrowserslistCheck = Boolean(expectedEcmaVersion === "checkBrowser" || checkBrowser);
 
   if (isBrowserslistCheck) {
-    const browserslistQuery = config.browserslistQuery;
+    const browserslistOptions = {
+      browserslistQuery: config.browserslistQuery,
+      browserslistPath: config.browserslistPath,
+      browserslistEnv: config.browserslistEnv,
+    };
     let browserslistError = null;
     let ecmaVersion = null;
+    let targetBrowsers = [];
 
     try {
-      const { getESVersionFromBrowserslist } = require("../browserslist");
-      const esVersionFromBrowserslist = getESVersionFromBrowserslist({
-        browserslistQuery,
-        browserslistPath: config.browserslistPath,
-        browserslistEnv: config.browserslistEnv,
-      });
+      const { getESVersionFromBrowserslist, getTargetBrowsers } = require("../browserslist");
+      const esVersionFromBrowserslist = getESVersionFromBrowserslist(browserslistOptions);
       ecmaVersion = esVersionFromBrowserslist.toString();
+      targetBrowsers = getTargetBrowsers(browserslistOptions);
     } catch (err) {
       browserslistError = err;
     }
@@ -220,7 +222,10 @@ function determineEcmaVersion(config, options) {
     const shouldDebug = hasNoError && isDebug;
 
     if (shouldDebug) {
-      logger.debug(`ES-Check: Using ES${ecmaVersion} based on browserslist configuration`);
+      const { formatTargetBrowsers } = require("../helpers/browserSupport");
+      logger.debug(
+        `ES-Check: Using ES${ecmaVersion} based on browserslist configuration (target browsers: ${formatTargetBrowsers(targetBrowsers)})`,
+      );
     }
 
     if (hasError) {
@@ -229,10 +234,10 @@ function determineEcmaVersion(config, options) {
         isNodeAPI,
         allErrors,
       });
-      return { ecmaVersion: null, hasError: true };
+      return { ecmaVersion: null, targetBrowsers: [], hasError: true };
     }
 
-    return { ecmaVersion, hasError: false };
+    return { ecmaVersion, targetBrowsers, hasError: false };
   }
 
   const mappedVersion = ECMA_VERSION_MAP[expectedEcmaVersion];
@@ -248,11 +253,11 @@ function determineEcmaVersion(config, options) {
 
   if (isInvalidVersion) {
     handleInvalidVersion({ logger, isNodeAPI, allErrors });
-    return { ecmaVersion: null, hasError: true };
+    return { ecmaVersion: null, targetBrowsers: [], hasError: true };
   }
 
   const ecmaVersion = String(ECMA_VERSION_TO_NUMBER[mappedVersion]);
-  return { ecmaVersion, hasError: false };
+  return { ecmaVersion, targetBrowsers: [], hasError: false };
 }
 
 function filterIgnoredFiles(files, pathsToIgnore, globOpts) {
@@ -283,7 +288,17 @@ function filterIgnoredFiles(files, pathsToIgnore, globOpts) {
   return files.filter(shouldKeepFile);
 }
 
-function processFullAST(code, acornOpts, file, config, ignoreList, ecmaVersion, isDebug, logger) {
+function processFullAST(
+  code,
+  acornOpts,
+  file,
+  config,
+  ignoreList,
+  ecmaVersion,
+  isDebug,
+  logger,
+  targetBrowsers,
+) {
   const needsFullAST = config.checkFeatures;
   const parserOptions = needsFullAST
     ? acornOpts
@@ -317,6 +332,7 @@ function processFullAST(code, acornOpts, file, config, ignoreList, ecmaVersion,
       ast,
       checkForPolyfills: config.checkForPolyfills,
       ignorePolyfillable: config.ignorePolyfillable,
+      targetBrowsers,
     });
     foundFeatures = result.foundFeatures;
     unsupportedFeatures = result.unsupportedFeatures;
@@ -398,7 +414,7 @@ function processFullAST(code, acornOpts, file, config, ignoreList, ecmaVersion,
 }
 
 function createFileProcessor(config, options) {
-  const { acornOpts, ignoreList, logger, isDebug, ecmaVersion } = options;
+  const { acornOpts, ignoreList, logger, isDebug, ecmaVersion, targetBrowsers } = options;
 
   return (file) => {
     const useCache = config.cache !== false;
@@ -411,7 +427,17 @@ function createFileProcessor(config, options) {
       logger.debug(`ES-Check: checking ${file}`);
     }
 
-    return processFullAST(code, acornOpts, file, config, ignoreList, ecmaVersion, isDebug, logger);
+    return processFullAST(
+      code,
+      acornOpts,
+      file,
+      config,
+      ignoreList,
+      ecmaVersion,
+      isDebug,
+      logger,
+      targetBrowsers,
+    );
   };
 }