Support sourceType: "commonjs" (#17390)

* feat: support sourceType: commonjs

* fix: improve eslint-parser souceType: commonjs handling

* allow sourceType: commonjs in babel/core

* set program.sourceType to script for commonjs

* feat: disallow some allow* parser flags in commonjs mode

* do not set allowReturnOutsideFunction for commonjs source type

* update error messages

* normalize Windows path

* fix option typo

* add souceType: "commonjs" compatibility layer

* update default ecmaVersion to latest

* update eslint-parser docs

---------

Co-authored-by: Nicolò Ribaudo <[email protected]>

Author: JLHwung

eslint/babel-eslint-parser/README.md

@@ -53,25 +53,25 @@ Additional configuration options can be set in your ESLint configuration under t
   Note: When `requireConfigFile` is `false`, @babel/eslint-parser will still try to load the root babel config. If no configuration file is found, @babel/eslint-parser will not parse any experimental syntax. Though not recommended, if you have a babel config, but would like to prevent @babel/eslint-parser from loading Babel config, please specify
   **.eslintrc.js**
 
-```js
-module.exports = {
-  parser: "@babel/eslint-parser",
-  parserOptions: {
-    requireConfigFile: false,
-    babelOptions: {
-      babelrc: false,
-      configFile: false,
-      // your babel options
-      presets: ["@babel/preset-env"],
+  ```js
+  module.exports = {
+    parser: "@babel/eslint-parser",
+    parserOptions: {
+      requireConfigFile: false,
+      babelOptions: {
+        babelrc: false,
+        configFile: false,
+        // your babel options
+        presets: ["@babel/preset-env"],
+      },
     },
-  },
-};
-```
+  };
+  ```
 
-- `sourceType` can be set to `"module"`(default) or `"script"` if your code isn't using ECMAScript modules.
+- `sourceType` can be set to `"module"`(default), `"script"` or `"commonjs"`.
 <!-- TODO(Babel 8): Remove this -->
 - `allowImportExportEverywhere` (default `false`) can be set to `true` to allow import and export declarations to appear anywhere a statement is allowed if your build environment supports that. Otherwise import and export declarations can only appear at a program's top level.
-- `ecmaFeatures.globalReturn` (default `false`) allow return statements in the global scope when used with `sourceType: "script"`.
+- `ecmaFeatures.globalReturn` (default `false`) allow return statements in the global scope when used with `sourceType: "script"`. This option will be deprecated, please use `sourceType: "commonjs"` instead.
 - `babelOptions` is an object containing Babel configuration [options](https://babeljs.io/docs/en/options) that are passed to Babel's parser at runtime. For cases where users might not want to use a Babel configuration file or are running Babel through another tool (such as Webpack with `babel-loader`).
 
 **.eslintrc.js**

eslint/babel-eslint-parser/src/configuration.cts

@@ -4,7 +4,7 @@ export = function normalizeESLintConfig(options: any) {
   const {
     babelOptions = {},
     // ESLint sets ecmaVersion: undefined when ecmaVersion is not set in the config.
-    ecmaVersion = 2020,
+    ecmaVersion = "latest",
     sourceType = "module",
     requireConfigFile = true,
     ...otherOptions
@@ -13,9 +13,7 @@ export = function normalizeESLintConfig(options: any) {
   return {
     babelOptions: { cwd: process.cwd(), ...babelOptions },
     ecmaVersion: ecmaVersion === "latest" ? 1e8 : ecmaVersion,
-    // https://eslint.org/docs/latest/use/configure/language-options#specifying-javascript-options
-    // ESLint supports "commonjs" but Babel parser does not.
-    sourceType: sourceType === "commonjs" ? "script" : sourceType,
+    sourceType,
     requireConfigFile,
     ...otherOptions,
   } as Options;

eslint/babel-eslint-parser/src/worker/configuration.cts

@@ -1,4 +1,5 @@
 import babel = require("./babel-core.cts");
+import semver = require("semver");
 import ESLINT_VERSION = require("../utils/eslint-version.cts");
 import type { InputOptions } from "@babel/core";
 import type { Options } from "../types.cts";
@@ -24,12 +25,26 @@ function getParserPlugins(
   return [["estree", estreeOptions], ...babelParserPlugins];
 }
 
-function normalizeParserOptions(options: Options): InputOptions & {
+function normalizeParserOptions(
+  options: Options,
+  version: string,
+): InputOptions & {
   showIgnoredFiles?: boolean;
 } {
+  // Babel <= 7.28.0 does not support `sourceType: "commonjs"`.
+  if (
+    !process.env.BABEL_8_BREAKING &&
+    options.sourceType === "commonjs" &&
+    !semver.satisfies(version, REQUIRED_VERSION(">=7.28.0"))
+  ) {
+    options.sourceType = "script";
+    options.ecmaFeatures = {
+      ...(options.ecmaFeatures ?? {}),
+      globalReturn: true,
+    };
+  }
   return {
-    // https://github.com/eslint/js/issues/519
-    sourceType: options.sourceType as "module" | "script",
+    sourceType: options.sourceType,
     filename: options.filePath,
     ...options.babelOptions,
     parserOpts: {
@@ -40,9 +55,13 @@ function normalizeParserOptions(options: Options): InputOptions & {
               options.allowImportExportEverywhere ?? false,
             allowSuperOutsideMethod: true,
           }),
-      allowReturnOutsideFunction:
-        options.ecmaFeatures?.globalReturn ??
-        (process.env.BABEL_8_BREAKING ? false : true),
+      ...(options.sourceType !== "commonjs"
+        ? {
+            allowReturnOutsideFunction:
+              options.ecmaFeatures?.globalReturn ??
+              (process.env.BABEL_8_BREAKING ? false : true),
+          }
+        : {}),
       ...options.babelOptions.parserOpts,
       plugins: getParserPlugins(options.babelOptions),
       // skip comment attaching for parsing performance
@@ -95,13 +114,13 @@ function getDefaultParserOptions(options: InputOptions): InputOptions {
 export async function normalizeBabelParseConfig(
   options: Options,
 ): Promise<InputOptions> {
-  const parseOptions = normalizeParserOptions(options);
+  const parseOptions = normalizeParserOptions(options, babel.version);
   const config = await babel.loadPartialConfigAsync(parseOptions);
   return validateResolvedConfig(config, options, parseOptions);
 }
 
 export function normalizeBabelParseConfigSync(options: Options): InputOptions {
-  const parseOptions = normalizeParserOptions(options);
+  const parseOptions = normalizeParserOptions(options, babel.version);
   const config = babel.loadPartialConfigSync(parseOptions);
   return validateResolvedConfig(config, options, parseOptions);
 }

eslint/babel-eslint-tests/test/integration/eslint/config.js

@@ -22,9 +22,9 @@ describe("ESLint config", () => {
   });
 
   it('should allow sourceType to be "commonjs"', () => {
-    // sourceType "commonjs" allows require() calls.
+    // sourceType "commonjs" allows require() calls and global returns
     verifyAndAssertMessages(
-      'require("greetings").hello',
+      'return require("greetings").hello',
       {},
       undefined,
       undefined,

packages/babel-core/src/config/validation/option-assertions.ts

@@ -125,11 +125,12 @@ export function assertSourceType(
   if (
     value !== undefined &&
     value !== "module" &&
+    value !== "commonjs" &&
     value !== "script" &&
     value !== "unambiguous"
   ) {
     throw new Error(
-      `${msg(loc)} must be "module", "script", "unambiguous", or undefined`,
+      `${msg(loc)} must be "module", "commonjs", "script", "unambiguous", or undefined`,
     );
   }
   // @ts-expect-error: TS can only narrow down the type when "strictNullCheck" is true

packages/babel-core/src/config/validation/options.ts

@@ -232,7 +232,7 @@ export type ConfigApplicableTest = IgnoreItem | Array<IgnoreItem>;
 export type ConfigFileSearch = string | boolean;
 export type BabelrcSearch = boolean | IgnoreItem | IgnoreList;
 export type SourceMapsOption = boolean | "inline" | "both";
-export type SourceTypeOption = "module" | "script" | "unambiguous";
+export type SourceTypeOption = "module" | "commonjs" | "script" | "unambiguous";
 export type CompactOption = boolean | "auto";
 export type RootInputSourceMapOption = object | boolean;
 export type RootMode = "root" | "upward" | "upward-optional";

packages/babel-core/test/errors-stacks.js

@@ -235,7 +235,7 @@ describe("@babel/core errors", function () {
         root: fixture("invalid-option"),
       });
     }).toMatchInlineSnapshot(`
-      "Error: .sourceType must be \\"module\\", \\"script\\", \\"unambiguous\\", or undefined
+      "Error: .sourceType must be \\"module\\", \\"commonjs\\", \\"script\\", \\"unambiguous\\", or undefined
           at <CWD>/packages/babel-core/test/fixtures/errors/invalid-option/babel.config.json
           at Module.parseSync (<CWD>/packages/babel-core/src/parse.ts:_:_)
           at <CWD>/packages/babel-core/test/errors-stacks.js:_:_
@@ -252,7 +252,7 @@ describe("@babel/core errors", function () {
         sourceType: "foo",
       }),
     ).toMatchInlineSnapshot(`
-      "Error: .sourceType must be \\"module\\", \\"script\\", \\"unambiguous\\", or undefined
+      "Error: .sourceType must be \\"module\\", \\"commonjs\\", \\"script\\", \\"unambiguous\\", or undefined
           at Module.parseSync (<CWD>/packages/babel-core/src/parse.ts:_:_)
           at <CWD>/packages/babel-core/test/errors-stacks.js:_:_
           at expectError (<CWD>/packages/babel-core/test/errors-stacks.js:_:_)

packages/babel-parser/data/schema.json

@@ -252,8 +252,8 @@
       "type": "string"
     },
     "sourceType": {
-      "description": "Indicate the mode the code should be parsed in.\nCan be one of \"script\", \"module\", or \"unambiguous\". Defaults to \"script\".\n\"unambiguous\" will make @babel/parser attempt to guess, based on the presence\nof ES6 import or export statements.\nFiles with ES6 imports and exports are considered \"module\" and are otherwise \"script\".",
-      "enum": ["module", "script", "unambiguous"],
+      "description": "Indicate the mode the code should be parsed in.\nCan be one of \"script\", \"commonjs\", \"module\", or \"unambiguous\". Defaults to \"script\".\n\"unambiguous\" will make @babel/parser attempt to guess, based on the presence\nof ES6 import or export statements.\nFiles with ES6 imports and exports are considered \"module\" and are otherwise \"script\".",
+      "enum": ["module", "commonjs", "script", "unambiguous"],
       "type": "string"
     },
     "startLine": {

packages/babel-parser/src/options.ts

@@ -3,7 +3,7 @@ import type { Plugin } from "./plugin-utils.ts";
 // A second optional argument can be given to further configure
 // the parser process. These options are recognized:
 
-export type SourceType = "script" | "module" | "unambiguous";
+export type SourceType = "script" | "commonjs" | "module" | "unambiguous";
 
 export interface Options {
   /**
@@ -71,12 +71,14 @@ export interface Options {
 
   /**
    * Indicate the mode the code should be parsed in.
-   * Can be one of "script", "module", or "unambiguous". Defaults to "script".
+   * Can be one of "script", "commonjs", "module", or "unambiguous". Defaults to "script".
    * "unambiguous" will make @babel/parser attempt to guess, based on the presence
    * of ES6 import or export statements.
    * Files with ES6 imports and exports are considered "module" and are otherwise "script".
+   *
+   * Use "commonjs" to parse code that is intended to be run in a CommonJS environment such as Node.js.
    */
-  sourceType?: "script" | "module" | "unambiguous";
+  sourceType?: SourceType;
 
   /**
    * Correlate output AST nodes with their source filename.
@@ -261,5 +263,23 @@ export function getOptions(opts?: Options | null): OptionsWithDefaults {
     }
   }
 
+  if (options.sourceType === "commonjs") {
+    if (opts.allowAwaitOutsideFunction != null) {
+      throw new Error(
+        "The `allowAwaitOutsideFunction` option cannot be used with `sourceType: 'commonjs'`.",
+      );
+    }
+    if (opts.allowReturnOutsideFunction != null) {
+      throw new Error(
+        "`sourceType: 'commonjs'` implies `allowReturnOutsideFunction: true`, please remove the `allowReturnOutsideFunction` option or use `sourceType: 'script'`.",
+      );
+    }
+    if (opts.allowNewTargetOutsideFunction != null) {
+      throw new Error(
+        "`sourceType: 'commonjs'` implies `allowNewTargetOutsideFunction: true`, please remove the `allowNewTargetOutsideFunction` option or use `sourceType: 'script'`.",
+      );
+    }
+  }
+
   return options;
 }

packages/babel-parser/src/parser/statement.ts

@@ -200,7 +200,11 @@ export default abstract class StatementParser extends ExpressionParser {
     file: Undone<N.File>,
     program: Undone<N.Program>,
   ): N.File {
-    file.program = this.parseProgram(program);
+    file.program = this.parseProgram(
+      program,
+      tt.eof,
+      this.options.sourceType === "module" ? "module" : "script",
+    );
     file.comments = this.comments;
 
     if (this.optionFlags & OptionFlags.Tokens) {
@@ -217,8 +221,8 @@ export default abstract class StatementParser extends ExpressionParser {
   parseProgram(
     this: Parser,
     program: Undone<N.Program>,
-    end: TokenType = tt.eof,
-    sourceType: SourceType = this.options.sourceType,
+    end: TokenType,
+    sourceType: SourceType,
   ): N.Program {
     program.sourceType = sourceType;
     program.interpreter = this.parseInterpreterDirective();