es-check 8.0.0 → 8.0.1-0

package/constants.js

@@ -0,0 +1,500 @@
+/**
+ * Map of ES features (by name) → earliest ES minVersion + AST detection hints
+ * ES6 (2015) = 6, ES7 (2016) = 7, ES8 (2017) = 8, ES9 (2018) = 9,
+ * ES10 (2019) = 10, ES11 (2020) = 11, ES12 (2021) = 12,
+ * ES13 (2022) = 13, ES14 (2023) = 14, etc.
+ */
+const ES_FEATURES = {
+  // ----------------------------------------------------------
+  // ES6 / ES2015
+  // ----------------------------------------------------------
+  ArraySpread: {
+    minVersion: 6,
+    example: '[...arr]',
+    astInfo: {
+      nodeType: 'ArrayExpression',
+      childType: 'SpreadElement',
+    },
+  },
+  let: {
+    minVersion: 6,
+    example: 'let x = 10;',
+    astInfo: {
+      nodeType: 'VariableDeclaration',
+      kind: 'let',
+    },
+  },
+  const: {
+    minVersion: 6,
+    example: 'const x = 10;',
+    astInfo: {
+      nodeType: 'VariableDeclaration',
+      kind: 'const',
+    },
+  },
+  class: {
+    minVersion: 6,
+    example: 'class MyClass {}',
+    astInfo: {
+      nodeType: 'ClassDeclaration',
+    },
+  },
+  extends: {
+    minVersion: 6,
+    example: 'class MyClass extends OtherClass {}',
+    astInfo: {
+      nodeType: 'ClassDeclaration',
+      property: 'superClass',
+    },
+  },
+  import: {
+    minVersion: 6,
+    example: 'import * as mod from "mod";',
+    astInfo: {
+      nodeType: 'ImportDeclaration',
+    },
+  },
+  export: {
+    minVersion: 6,
+    example: 'export default x;',
+    astInfo: {
+      nodeType: 'ExportDeclaration',
+    },
+  },
+  ArrowFunctions: {
+    minVersion: 6,
+    example: 'const fn = () => {};',
+    astInfo: {
+      nodeType: 'ArrowFunctionExpression',
+    },
+  },
+  TemplateLiterals: {
+    minVersion: 6,
+    example: 'const str = `Hello, ${name}!`;',
+    astInfo: {
+      nodeType: 'TemplateLiteral',
+    },
+  },
+  Destructuring: {
+    minVersion: 6,
+    example: 'const { x } = obj;',
+    astInfo: {
+      nodeType: 'ObjectPattern',
+    },
+  },
+  DefaultParams: {
+    minVersion: 6,
+    example: 'function foo(x=10) {}',
+    astInfo: {
+      nodeType: 'AssignmentPattern',
+    },
+  },
+  RestSpread: {
+    minVersion: 6,
+    example: 'function(...args) {}',
+    astInfo: {
+      nodeType: 'RestElement',
+    },
+  },
+  ForOf: {
+    minVersion: 6,
+    example: 'for (const x of iterable) {}',
+    astInfo: {
+      nodeType: 'ForOfStatement',
+    },
+  },
+  Map: {
+    minVersion: 6,
+    example: 'new Map()',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'Map',
+    },
+  },
+  Set: {
+    minVersion: 6,
+    example: 'new Set()',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'Set',
+    },
+  },
+  WeakMap: {
+    minVersion: 6,
+    example: 'new WeakMap()',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'WeakMap',
+    },
+  },
+  WeakSet: {
+    minVersion: 6,
+    example: 'new WeakSet()',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'WeakSet',
+    },
+  },
+  Promise: {
+    minVersion: 6,
+    example: 'new Promise((resolve, reject) => {})',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'Promise',
+    },
+  },
+  Symbol: {
+    minVersion: 6,
+    example: 'Symbol("desc")',
+    astInfo: {
+      nodeType: 'CallExpression',
+      callee: 'Symbol',
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES7 / ES2016
+  // ----------------------------------------------------------
+  ExponentOperator: {
+    minVersion: 7,
+    example: 'a ** b',
+    astInfo: {
+      nodeType: 'BinaryExpression',
+      operator: '**',
+    },
+  },
+  ArrayPrototypeIncludes: {
+    minVersion: 7,
+    example: 'arr.includes(x)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'includes',
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES8 / ES2017
+  // ----------------------------------------------------------
+  AsyncAwait: {
+    minVersion: 8,
+    example: 'async function foo() { await bar(); }',
+    astInfo: {
+      nodeType: 'AwaitExpression',
+    },
+  },
+  ObjectValues: {
+    minVersion: 8,
+    example: 'Object.values(obj)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      object: 'Object',
+      property: 'values',
+    },
+  },
+  ObjectEntries: {
+    minVersion: 8,
+    example: 'Object.entries(obj)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      object: 'Object',
+      property: 'entries',
+    },
+  },
+  StringPadStart: {
+    minVersion: 8,
+    example: 'str.padStart(10)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'padStart',
+    },
+  },
+  StringPadEnd: {
+    minVersion: 8,
+    example: 'str.padEnd(10)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'padEnd',
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES9 / ES2018
+  // ----------------------------------------------------------
+  ObjectSpread: {
+    minVersion: 9,
+    example: 'const obj2 = { ...obj};',
+    astInfo: {
+      nodeType: 'ObjectExpression',
+      childType: 'SpreadElement',
+    },
+  },
+  AsyncIteration: {
+    minVersion: 9,
+    example: 'for await (const x of asyncIterable) {}',
+    astInfo: {
+      nodeType: 'ForAwaitStatement',
+    },
+  },
+  PromiseFinally: {
+    minVersion: 9,
+    example: 'promise.finally(() => {})',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'finally',
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES10 / ES2019
+  // ----------------------------------------------------------
+  ArrayFlat: {
+    minVersion: 10,
+    example: 'arr.flat()',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'flat',
+    },
+  },
+  ArrayFlatMap: {
+    minVersion: 10,
+    example: 'arr.flatMap(x => x)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'flatMap',
+    },
+  },
+  ObjectFromEntries: {
+    minVersion: 10,
+    example: 'Object.fromEntries(entries)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      object: 'Object',
+      property: 'fromEntries',
+    },
+  },
+  OptionalCatchBinding: {
+    minVersion: 10,
+    example: 'try { ... } catch { ... }',
+    astInfo: {
+      nodeType: 'CatchClause',
+      noParam: true,
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES11 / ES2020
+  // ----------------------------------------------------------
+  BigInt: {
+    minVersion: 11,
+    example: '123n',
+    astInfo: {
+      nodeType: 'BigIntLiteral',
+    },
+  },
+  DynamicImport: {
+    minVersion: 11,
+    example: 'import("module.js")',
+    astInfo: {
+      nodeType: 'ImportExpression',
+    },
+  },
+  OptionalChaining: {
+    minVersion: 11,
+    example: 'obj?.prop',
+    astInfo: {
+      nodeType: 'ChainExpression',
+    },
+  },
+  NullishCoalescing: {
+    minVersion: 11,
+    example: 'a ?? b',
+    astInfo: {
+      nodeType: 'LogicalExpression',
+      operator: '??',
+    },
+  },
+  globalThis: {
+    minVersion: 11,
+    example: 'globalThis',
+    astInfo: {
+      nodeType: 'Identifier',
+      name: 'globalThis',
+    },
+  },
+  PromiseAllSettled: {
+    minVersion: 11,
+    example: 'Promise.allSettled(promises)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'allSettled',
+    },
+  },
+  StringMatchAll: {
+    minVersion: 11,
+    example: 'str.matchAll(regex)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'matchAll',
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES12 / ES2021
+  // ----------------------------------------------------------
+  LogicalAssignment: {
+    minVersion: 12,
+    example: 'x &&= y;',
+    astInfo: {
+      nodeType: 'AssignmentExpression',
+      operators: ['&&=', '||=', '??='],
+    },
+  },
+  NumericSeparators: {
+    minVersion: 12,
+    example: '1_000_000',
+    astInfo: {
+      nodeType: 'NumericLiteralWithSeparator',
+    },
+  },
+  StringReplaceAll: {
+    minVersion: 12,
+    example: 'str.replaceAll("a", "b")',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'replaceAll',
+    },
+  },
+  PromiseAny: {
+    minVersion: 12,
+    example: 'Promise.any(promises)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'any',
+    },
+  },
+  WeakRef: {
+    minVersion: 12,
+    example: 'new WeakRef(obj)',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'WeakRef',
+    },
+  },
+  FinalizationRegistry: {
+    minVersion: 12,
+    example: 'new FinalizationRegistry(cb)',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'FinalizationRegistry',
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES13 / ES2022
+  // ----------------------------------------------------------
+  TopLevelAwait: {
+    minVersion: 13,
+    example: 'await foo()',
+    astInfo: {
+      nodeType: 'AwaitExpression',
+      topLevel: true,
+    },
+  },
+  PrivateClassFields: {
+    minVersion: 13,
+    example: 'class MyClass { #x = 1; }',
+    astInfo: {
+      nodeType: 'PropertyDefinition',
+      isPrivate: true,
+    },
+  },
+  ClassStaticBlocks: {
+    minVersion: 13,
+    example: 'class MyClass { static {} }',
+    astInfo: {
+      nodeType: 'StaticBlock',
+    },
+  },
+  ErgonomicBrandChecks: {
+    minVersion: 13,
+    example: '#field in obj',
+    astInfo: {
+      nodeType: 'BinaryExpression',
+      operator: 'in',
+      leftIsPrivate: true,
+    },
+  },
+  ErrorCause: {
+    minVersion: 13,
+    example: 'new Error("...", { cause: e })',
+    astInfo: {
+      nodeType: 'NewExpression',
+      callee: 'Error',
+      hasOptionsCause: true,
+    },
+  },
+  ArrayPrototypeAt: {
+    minVersion: 13,
+    example: 'arr.at(-1)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'at',
+    },
+  },
+
+  // ----------------------------------------------------------
+  // ES14 / ES2023
+  // ----------------------------------------------------------
+  Hashbang: {
+    minVersion: 14,
+    example: '#!/usr/bin/env node',
+    astInfo: {
+      nodeType: 'Hashbang',
+    },
+  },
+  ArrayToReversed: {
+    minVersion: 14,
+    example: 'arr.toReversed()',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'toReversed',
+    },
+  },
+  ArrayToSorted: {
+    minVersion: 14,
+    example: 'arr.toSorted(compareFn)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'toSorted',
+    },
+  },
+  ArrayToSpliced: {
+    minVersion: 14,
+    example: 'arr.toSpliced(start, deleteCount, ...)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'toSpliced',
+    },
+  },
+  ArrayWith: {
+    minVersion: 14,
+    example: 'arr.with(index, value)',
+    astInfo: {
+      nodeType: 'CallExpression',
+      property: 'with',
+    },
+  },
+};
+
+const NODE_TYPES = {
+  VARIABLE_DECLARATION: 'VariableDeclaration',
+  ARROW_FUNCTION_EXPRESSION: 'ArrowFunctionExpression',
+  CHAIN_EXPRESSION: 'ChainExpression',
+  LOGICAL_EXPRESSION: 'LogicalExpression',
+  NEW_EXPRESSION: 'NewExpression',
+};
+
+module.exports = {
+  ES_FEATURES,
+  NODE_TYPES,
+};

package/detectFeatures.js

@@ -0,0 +1,83 @@
+const acorn = require('acorn');
+const walk = require('acorn-walk');
+const { ES_FEATURES } = require('./constants');
+const { checkMap } = require('./utils');
+
+const detectFeatures = (code, ecmaVersion, sourceType) => {
+  const ast = acorn.parse(code, {
+    ecmaVersion: 'latest',
+    sourceType,
+  });
+
+  /**
+   * @note Flatten all checks
+   */
+  const allChecks = Object.entries(ES_FEATURES).map(([featureName, { astInfo }]) => ({
+    featureName,
+    nodeType: astInfo.nodeType,
+    astInfo,
+  }));
+
+  /**
+   * @note A universal visitor for any node type:
+   * - Filters checks that match the current node’s type
+   * - Calls the relevant checker function
+   * - If true => mark the feature as found
+   */
+  const foundFeatures = Object.keys(ES_FEATURES).reduce((acc, f) => {
+    acc[f] = false;
+    return acc;
+  }, {});
+
+  const universalVisitor = (node) => {
+    allChecks
+      .filter(({ nodeType }) => nodeType === node.type)
+      .forEach(({ featureName, astInfo }) => {
+        const checker = checkMap[node.type] || checkMap.default;
+        if (checker(node, astInfo)) {
+          foundFeatures[featureName] = true;
+        }
+      });
+  };
+
+  /**
+   * @note Build the visitors object for acorn-walk.
+   * Each unique nodeType gets the same universalVisitor.
+   */
+  const nodeTypes = [...new Set(allChecks.map((c) => c.nodeType))];
+  const visitors = nodeTypes.reduce((acc, nt) => {
+    acc[nt] = universalVisitor;
+    return acc;
+  }, {});
+
+  walk.simple(ast, visitors);
+
+  /**
+   * @note Check if any found feature requires a higher version than requested.
+   * We assume each entry in ES_FEATURES has a `minVersion` property.
+   */
+  const unsupportedFeatures = Object.entries(ES_FEATURES).reduce((acc = [], [featureName, { minVersion }]) => {
+    // If feature is used but requires a newer version than ecmaVersion, it's unsupported
+    if (foundFeatures[featureName] && minVersion > ecmaVersion) {
+      acc.push(featureName);
+    }
+    return acc;
+  }, []);
+
+  /**
+   * @note Fail if any unsupported features were used.
+   */
+  if (unsupportedFeatures.length > 0) {
+    throw new Error(
+      `Unsupported features detected: ${unsupportedFeatures.join(', ')}. ` +
+      `These require a higher ES version than ${ecmaVersion}.`
+    );
+  }
+
+  return {
+    foundFeatures,
+    unsupportedFeatures,
+  }
+};
+
+module.exports = detectFeatures;

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "es-check",
-  "version": "8.0.0",
+  "version": "8.0.1-0",
   "description": "Checks the ECMAScript version of .js glob against a specified version of ECMAScript with a shell command",
   "main": "index.js",
   "license": "MIT",
   "files": [
-    "index.js"
+    "index.js",
+    "utils.js",
+    "detectFeatures.js",
+    "constants.js"
   ],
   "bin": {
     "es-check": "index.js"

package/utils.js

@@ -0,0 +1,164 @@
+/**
+ * @note Checks if node.kind === astInfo.kind (e.g., 'const', 'let').
+ */
+const checkVarKindMatch = (node, astInfo) => {
+  if (!astInfo.kind) return false;
+  return node.kind === astInfo.kind;
+}
+
+/**
+ * @note Checks if a NewExpression node's callee is an Identifier
+ * that matches astInfo.callee (e.g. "Promise", "WeakRef").
+ */
+const checkCalleeMatch = (node, astInfo) => {
+  if (!astInfo.callee) return false;
+  // e.g. node.callee.type === 'Identifier' && node.callee.name === 'Promise'
+  if (!node.callee || node.callee.type !== 'Identifier') return false;
+  return node.callee.name === astInfo.callee;
+}
+
+/**
+ * @note Checks if a LogicalExpression node's operator matches astInfo.operator (e.g., '??').
+ */
+const checkOperatorMatch = (node, astInfo) =>{
+  if (!astInfo.operator) return false;
+  return node.operator === astInfo.operator;
+}
+
+/**
+ * @note For simple presence-based checks (e.g., ArrowFunctionExpression).
+ */
+const checkDefault = () => {
+  return true;
+}
+
+/**
+ * @note A more "universal" check for a CallExpression, used for many ES features:
+ *   - arrayMethod => property: 'flat', 'includes', 'at', etc.
+ *   - objectMethod => object: 'Object', property: 'fromEntries', etc.
+ */
+const checkCallExpression = (node, astInfo) => {
+  // Must be `CallExpression`
+  if (node.type !== 'CallExpression') return false;
+
+  // We might check if node.callee is a MemberExpression, e.g. array.includes(...)
+  // or if node.callee is an Identifier, e.g. Symbol(...).
+  if (node.callee.type === 'MemberExpression') {
+    const { object, property } = astInfo;
+    // e.g. object: 'Object', property: 'entries'
+    // => node.callee.object.name === 'Object' && node.callee.property.name === 'entries'
+    if (object) {
+      if (
+        !node.callee.object ||
+        node.callee.object.type !== 'Identifier' ||
+        node.callee.object.name !== object
+      ) {
+        return false;
+      }
+    }
+    if (property) {
+      // e.g. property: 'includes'
+      if (!node.callee.property || node.callee.property.name !== property) {
+        return false;
+      }
+    }
+    return true;
+  } else if (node.callee.type === 'Identifier') {
+    // e.g. Symbol("desc")
+    const { callee } = astInfo;
+    // If astInfo.callee is "Symbol", check node.callee.name
+    if (callee && node.callee.name === callee) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * @note Check ObjectExpression for childType, e.g. 'SpreadElement'
+ */
+const checkObjectExpression = (node, astInfo) => {
+  // If we want to detect object spread, we might check if node.properties
+  // contain a SpreadElement
+  if (astInfo.childType === 'SpreadElement') {
+    return node.properties.some((p) => p.type === 'SpreadElement');
+  }
+  return false;
+}
+
+/**
+ * @note Check ClassDeclaration presence or superClass usage
+ */
+const checkClassDeclaration = (node, astInfo) => {
+  // Just having a ClassDeclaration means classes are used.
+  // If astInfo has `property: 'superClass'`, it means "extends" usage
+  if (astInfo.property === 'superClass') {
+    return !!node.superClass; // if superClass is not null, "extends" is used
+  }
+  return true; // default: any ClassDeclaration means the feature is used
+}
+
+/**
+ * @note Example check for BinaryExpression (e.g., exponent operator `**`).
+ */
+const checkBinaryExpression = (node, astInfo) => {
+  if (!astInfo.operator) return false;
+  return node.operator === astInfo.operator;
+}
+
+const checkForAwaitStatement = (node) => {
+  return true;
+}
+
+/**
+ * @note Example check for CatchClause with no param => optional catch binding
+ */
+const checkCatchClause = (node, astInfo) => {
+  if (astInfo.noParam) {
+    return !node.param;
+  }
+  return false;
+}
+
+/**
+ * @note Example check for BigIntLiteral or numeric with underscore
+ */
+const checkBigIntLiteral = (node) =>{
+  if (typeof node.value === 'bigint') {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * @note the "catch-all" object mapping node types to specialized checkers
+ */
+const checkMap = {
+  VariableDeclaration: (node, astInfo) => checkVarKindMatch(node, astInfo),
+  ArrowFunctionExpression: () => checkDefault(),
+  ChainExpression: () => checkDefault(),
+  LogicalExpression: (node, astInfo) => checkOperatorMatch(node, astInfo),
+  NewExpression: (node, astInfo) => checkCalleeMatch(node, astInfo),
+  CallExpression: (node, astInfo) => checkCallExpression(node, astInfo),
+  ObjectExpression: (node, astInfo) => checkObjectExpression(node, astInfo),
+  ClassDeclaration: (node, astInfo) => checkClassDeclaration(node, astInfo),
+  BinaryExpression: (node, astInfo) => checkBinaryExpression(node, astInfo),
+  ForAwaitStatement: (node) => checkForAwaitStatement(node),
+  CatchClause: (node, astInfo) => checkCatchClause(node, astInfo),
+  Literal: (node, astInfo) => {
+    if (astInfo.nodeType === 'BigIntLiteral') {
+      return checkBigIntLiteral(node);
+    }
+    return false;
+  },
+  default: () => false,
+};
+
+module.exports = {
+  checkVarKindMatch,
+  checkCalleeMatch,
+  checkOperatorMatch,
+  checkDefault,
+  checkMap,
+};