chore: improve the code and the doc

.changeset/soft-experts-roll.md

@@ -17,6 +17,7 @@ swc conversion was introduced in version 2.16.0, but the implementation still ha
 7. fix some css module bugs.
 8. support buildConfig.jsx: preserve .
 9. support glob input in js and dts generator.
+10. support banner and footer.
 
 refactor(module-tools):
 
@@ -33,3 +34,4 @@ swc 转换是在 2.16.0 版本引入，但实现仍存在一些问题，例如 f
 7. 修复一些 css module 问题。
 8. 支持 buildConfig.jsx: preserve 选项。
 9. 支持 glob 模式输入在 js 和 dts 生成器中。
+10. 支持 banner 和 footer 配置。

packages/document/module-doc/docs/en/api/config/build-config.mdx

@@ -211,6 +211,47 @@ Whether to require peerDep dependencies for external projects
 - **Type**: `boolean`
 - **Default**: `true`
 
+
+## banner
+
+Provides the ability to inject content into the top and bottom of each JS , CSS and DTS file.
+
+```ts
+interface BannerAndFooter {
+  js?: string;
+  css?: string;
+  dts?: string;
+}
+```
+
+- **Type**: `BannerAndFooter`
+- **Default**: `{}`
+- **Version**: `v2.36.0`
+
+Let's say you want to add copyright information to JS and CSS files.
+
+```ts
+import { moduleTools, defineConfig } from '@edenx/module-tools';
+
+const copyRight = `/*
+ © Copyright 2020 xxx.com or one of its affiliates.
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+*/`;
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+  ],
+  buildConfig: {
+    banner: {
+      js: copyRight,
+      css: copyRight,
+    }
+  }
+});
+```
+
 ## buildType
 
 The build type, `bundle` will package your code, `bundleless` will only do the code conversion
@@ -539,6 +580,10 @@ export default defineConfig({
 });
 ```
 
+## footer
+
+Same as the [banner](#banner) configuration for adding a comment at the end of the output file.
+
 ## format
 
 Used to set the output format of JavaScript files. The options `iife` and `umd` only take effect when `buildType` is `bundle`.
@@ -788,6 +833,59 @@ export default {
 };
 ```
 
+## resolve
+
+Custom module resolution options
+
+### resolve.mainFields
+
+A list of fields in package.json to try when parsing the package entry point.
+
+- **Type**: `string[]`
+- **Default**: depends on [platform](#platform)
+  - node: ['module', 'main']
+  - browser: ['module', 'browser', 'main']
+- **Version**: `v2.36.0`
+
+For example, we want to load the `js:source` field first:
+
+```js title="modern.config.ts"
+export default defineConfig({
+  buildConfig: {
+    resolve: {
+      mainFields: ['js:source', 'module', 'main'],
+    }
+  },
+});
+```
+
+:::warning
+`resolve.mainFields` has a lower priority than the exports field in package.json, and if an entry point is successfully resolved from exports, `resolve.mainFields` will be ignored.
+:::
+
+### resolve.jsExtentions
+
+Support for implicit file extensions
+
+- **Type**: `string[]`
+- **Default**: `['.jsx', '.tsx', '.js', '.ts', '.json']`
+- **Version**: `v2.36.0`
+
+
+Do not use implicit file extensions for css files, currently Module only supports ['.less', '.css', '.sass', '.scss'] suffixes.
+
+Node's parsing algorithm does not consider `.mjs` and `cjs` as implicit file extensions, so they are not included here by default, but can be included by changing this configuration:
+
+```js title="modern.config.ts"
+export default defineConfig({
+  buildConfig: {
+    resolve: {
+      jsExtentions: ['.mts', 'ts']
+    }
+  },
+});
+```
+
 ## sideEffects
 
 Module sideEffects
@@ -1275,6 +1373,7 @@ Path to the tsconfig file
 
 - **Type**: `string`
 - **Default**: `tsconfig.json`
+- **Version**: `v2.36.0`
 
 ```js title="modern.config.ts"
 export default defineConfig({

packages/document/module-doc/docs/en/guide/advance/in-depth-about-build.md

@@ -65,7 +65,9 @@ export default defineConfig({
 
 ## use swc
 
-In some scenarios, esbuild is not enough to meet our needs, then we will use swc to do the code transformation, mainly in the following scenarios.
+In some scenarios, esbuild is not enough to meet our needs, and we will use swc to do the code conversion.
+
+Starting from version **2.36.0**, the Modern.js Module will use swc by default when it comes to the following functionality, but that doesn't mean we don't use esbuild any more, the rest of the functionality will still use esbuild.
 
 - [transformImport](/api/config/build-config#transformimport)
 - [transformLodash](/api/config/build-config#transformlodash)
@@ -74,6 +76,9 @@ In some scenarios, esbuild is not enough to meet our needs, then we will use swc
 - [target: es5](api/config/build-config#target)
 - [emitDecoratorMetadata: true](https://www.typescriptlang.org/tsconfig#emitDecoratorMetadata)
 
+In fact, we've been using swc for full code conversion since **2.16.0**. However, swc also has some limitations, so we added [sourceType](/api/config/build-config#sourcetype) to turn off swc when the source is formatted as 'commonjs', which isn't really user-intuitive, and the cjs mode of the swc formatted outputs don't have annotate each export name, which can cause problems in node.
+So we deprecated this behaviour and went back to the original design - using swc as a supplement only in situations where it was needed.
+
 ## dts
 
 The [`buildConfig.dts`](/en/api/config/build-config#dts) configuration is mainly used for type file generation.
@@ -206,3 +211,42 @@ For `js/ts` build errors, we can tell from the error message.
 - What is the `format` of the build process
 - What is the `target` of the build process
 - The specific error message
+
+## Debug mode
+
+From **2.36.0**, For troubleshooting purposes, the Modern.js Module provides a debug mode, which you can enable by adding the DEBUG=module environment variable when executing a build.
+
+```bash
+DEBUG=module modern build
+```
+
+In debug mode, you'll see more detailed build logs output in Shell, which are mainly process logs:
+
+```bash
+module run beforeBuildTask hooks +6ms
+module run beforeBuildTask hooks done +0ms
+module [DTS] Build Start +139ms
+module [CJS] Build Start +1ms
+```
+
+In addition, Module provides the ability to debug internal workflows. You can enable more detailed debugging logging by setting the `DEBUG=module:*` environment variable.
+
+Currently, only `DEBUG=module:resolve` is supported, which allows you to see a detailed log of module resolution within the Module.
+
+```bash
+  module:resolve onResolve args: {
+  path: './src/hooks/misc.ts',
+  importer: '',
+  namespace: 'file',
+  resolveDir: '/Users/bytedance/modern.js/packages/solutions/module-tools',
+  kind: 'entry-point',
+  pluginData: undefined
+} +0ms
+  module:resolve onResolve result: {
+  path: '/Users/bytedance/modern.js/packages/solutions/module-tools/src/hooks/misc.ts',
+  external: false,
+  namespace: 'file',
+  sideEffects: undefined,
+  suffix: ''
+} +0ms
+```

packages/document/module-doc/docs/zh/api/config/build-config.mdx

@@ -212,6 +212,47 @@ export default defineConfig({
 - 类型： `boolean`
 - 默认值： `true`
 
+## banner
+
+提供为每个 JS , CSS 和 DTS 文件的顶部和底部注入内容的能力。
+
+```ts
+interface BannerAndFooter {
+  js?: string;
+  css?: string;
+  dts?: string;
+}
+```
+
+- 类型： `BannerAndFooter`
+- 默认值: `{}`
+- 版本： `v2.36.0`
+
+例如你想为 JS 和 CSS 文件添加版权信息:
+
+```ts
+import { moduleTools, defineConfig } from '@edenx/module-tools';
+
+const copyRight = `/*
+ © Copyright 2020 xxx.com or one of its affiliates.
+ * Some Sample Copyright Text Line
+ * Some Sample Copyright Text Line
+*/`;
+
+export default defineConfig({
+  plugins: [
+    moduleTools(),
+  ],
+  buildConfig: {
+    banner: {
+      js: copyRight,
+      css: copyRight,
+    }
+  }
+});
+```
+
+
 ## buildType
 
 构建类型，`bundle` 会打包你的代码，`bundleless` 只做代码的转换。
@@ -539,6 +580,10 @@ export default defineConfig({
 });
 ```
 
+## footer
+
+同 [banner](#banner) 配置，用于在输出文件末尾添加注释。
+
 ## format
 
 用于设置 JavaScript 产物输出的格式，其中 `iife` 和 `umd` 只在 `buildType` 为 `bundle` 时生效。
@@ -789,6 +834,60 @@ export default {
 };
 ```
 
+## resolve
+
+自定义模块解析选项
+
+### resolve.mainFields
+
+package.json 中，在解析包的入口点时尝试的字段列表。
+
+- 类型：`string[]`
+- 默认值：取决于[platform](#platform)
+  - node: ['module', 'main']
+  - browser: ['module', 'browser', 'main']
+- 版本：`v2.36.0`
+
+例如，我们想要先加载 `js:source` 字段：
+
+```js title="modern.config.ts"
+export default defineConfig({
+  buildConfig: {
+    resolve: {
+      mainFields: ['js:source', 'module', 'main'],
+    }
+  },
+});
+```
+
+:::warning
+`resolve.mainFields` 比 package.json 中 exports 字段的优先级低，如果一个入口点从 exports 成功解析，`resolve.mainFields` 将被忽略。
+:::
+
+### resolve.jsExtentions
+
+支持隐式文件扩展名
+
+- 类型： `string[]`
+- 默认值： `['.jsx', '.tsx', '.js', '.ts', '.json']`
+- 版本：`v2.36.0`
+
+
+对于 css 文件，请不要使用隐式文件扩展名，目前 Module 仅支持 ['.less', '.css', '.sass', '.scss'] 后缀。
+
+Node 的解析算法不会将 `.mjs` 和 `cjs` 视为隐式文件扩展名，因此这里默认也不会，但是可以通过更改此配置来包含：
+
+```js title="modern.config.ts"
+export default defineConfig({
+  buildConfig: {
+    resolve: {
+      jsExtentions: ['.mts', 'ts']
+    }
+  },
+});
+```
+
+
 ## sideEffects
 
 配置模块的副作用
@@ -849,6 +948,10 @@ export default defineConfig({
 
 ## sourceType
 
+:::warning
+已废弃，此配置不会产生任何影响。
+:::
+
 设置源码的格式。默认情况下，会将源码作为 EsModule 进行处理。当源码使用的是 CommonJS 的时候，需要设置 `commonjs`。
 
 - 类型：`'commonjs' | 'module'`
@@ -1273,6 +1376,7 @@ TypeScript 配置文件的路径。
 
 - 类型： `string`
 - 默认值： `tsconfig.json`
+- 版本： `v2.36.0`
 
 ```js title="modern.config.ts"
 export default defineConfig({