@modern-js/main-doc 2.0.0-beta.1 → 2.0.0-beta.2

package/zh/guides/topic-detail/generator/codesmith/api/app.md

@@ -0,0 +1,152 @@
+---
+sidebar_position: 1
+---
+
+# @modern-js/codesmith-api-app
+
+微生成器开发过程中常用 API 的组合封装，包含 fs、git、npm 等其他包的 API 封装，在能满足需求时，推荐使用该 npm 包的 API。
+
+## 使用姿势
+
+```typescript
+import { AppAPI } from '@modern-js/codesmith-api-app';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const appApi = new AppAPI(context, generator);
+  await appApi.runInstall();
+}
+```
+
+- 创建 AppAPI 实例，参数和微生成器函数参数一致，为 context 和 generator，具体介绍请看[微生成器项目组成](/docs/guides/topic-detail/generator/codesmith/structure)。
+- 调用其实例上 API 即可。
+
+## API
+
+### checkEnvironment
+
+检查当前生成器运行环境，检查项为：
+
+1. node 及 node 版本，默认大于 12.22.12，可传递参数执行 node 版本。
+2. 可使用 yarn、pnpm 或者 npm。
+
+参数：
+
+- nodeVersion?: `string` 校验的 node 版本。
+
+### runInstall
+
+安装依赖，可传入安装依赖命令，默认根据 config 中的 `packageManager` 值进行。
+
+参数：
+
+- command?: `string` 安装依赖命令。
+
+### runGitAndInstall
+
+该函数完成以下动作：
+
+1. 校验当前生成器执行目录是否为一个 git 仓库。
+2. 如果不是一个 git 仓库，初始化为一个 git 仓库。
+3. 安装依赖。
+4. 在非 monorepo 项目(判断条件，config 中 `isMonorepoSubProject` 不存在或者为 false)中提交初始 commit，commit 信息为 feat: init，支持自定义。
+
+参数：
+- commitMessage?: `string` 初始化 commit message 信息。
+- installFunc?: `() => Promise<void>` 安装依赖函数。
+
+### forgeTemplate
+
+渲染生成器模板文件。
+
+参数：
+
+- templatePattern: string 模板文件匹配正则，例如： `templates/base-templates/**/*` 。
+- filter?: `(resourceKey: string) => boolean` 过滤函数，参数为 templatePattern 匹配的文件路径，返回 true 表示渲染该文件，返回 false 表示不渲染该文件。
+- rename?: `(resourceKey: string) => string` 重命名函数，参数为 templatePattern 匹配的文件路径，返回新文件名。默认会替换 resourceKey 开头的 templates 目录和结尾的 .handlebars 后缀。
+- parameters?: `Record<string, any>` 渲染参数，当模板中存在 handlebars 或者 ejs 变量时，使用其传递对应变量值。
+- type?: `'handlebars' | 'ejs'`  模板文件类型，默认为 handlebars。
+
+例如:
+
+```typescript
+await appApi.forgeTemplate(
+    'templates/base-templates/**/*',
+    undefined,
+    resourceKey =>
+      resourceKey
+        .replace('templates/base-templates/', '')
+        .replace('.handlebars', ''),
+  );
+
+ await appApi.forgeTemplate(
+    'templates/base-template/**/*',
+    resourceKey => !resourceKey.include('eslintrc.json'),
+    resourceKey =>
+      resourceKey
+        .replace('templates/base-template/', projectPath)
+        .replace('language', language as string)
+        .replace('.handlebars', ''),
+    {
+      name: packageName as string,
+      language,
+      isTs: language === Language.TS,
+      packageManager: getPackageManagerText(packageManager as any),
+    },
+  );
+```
+
+### showSuccessInfo
+
+展示成功信息。
+
+参数：
+
+- successInfo?: `string`，默认为 Success || 成功。
+
+### runSubGenerator
+
+运行子生成器。
+
+参数：
+
+- subGenerator: `string` 子生成器名称或者路径。
+- relativePwdPath?: `string` 子生成器运行的相对路径。
+- config?: `Record<string, unknown>` 子生成器运行的默认 config 配置。
+
+例如：
+
+```typescript
+  await appApi.runSubGenerator(
+    getGeneratorPath('@modern-js/repo-generator', context.config.distTag),
+    undefined,
+    { ...context.config, hasPlugin: false },
+  );
+```
+
+### getInputBySchema
+
+通过 schema 完成用户交互输入。
+
+参数：
+
+- schema: `FormilySchema | Question[]` 问题列表，支持 Formily schema 和 inquirer 类型。
+- type: `'formily' | 'inquirer'` 类型，默认值为 formily。
+- configValue: `Record<string, unknown> = {}`  schema 默认值，传入该值的 schema 字段对应的问题将不再和用户交互。
+- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>` schema 中特殊字段的验证函数。
+- initValue?: `Record<string, any>` schema 中字段的初始化值。
+
+Formily Schema 类型支持方式可参考[自定义输入相关类型定义](/docs/guides/topic-detail/generator/plugin/api/input/type)。
+
+### getInputBySchemaFunc
+
+通过 schema 完成用户交互输入，schema 参数值为函数，用户处理国际化问题，仅支持 Formily schema。
+
+
+参数：
+
+- schema: `config?: Record<string, any>) => FormilySchema` 获取问题列表函数，config 参数为当前生成器中的 config 配置信息。
+- configValue: `Record<string, unknown> = {}`  schema 默认值，传入该值的 schema 字段对应的问题将不再和用户交互。
+- validateMap?: `Record<string, (input: unknown, data?: Record<string, unknown>) => { success: boolean; error?: string }>` schema 中特殊字段的验证函数。
+- initValue?: `Record<string, any>` schema 中字段的初始化值。
+
+Formily Schema 类型支持方式可参考[自定义输入相关类型定义](/docs/guides/topic-detail/generator/plugin/api/input/type)。

package/zh/guides/topic-detail/generator/codesmith/api/ejs.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 6
+---
+
+# @modern-js/codesmith-api-ejs
+
+微生成器中使用 [ejs](https://ejs.co/) 进行文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。
+
+## 使用姿势
+
+```typescript
+import { EjsAPI } from '@modern-js/codesmith-api-ejs';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const ejsAPI = new EjsAPI(generator);
+  await ejsAPI.renderTemplate(
+     material.get('templates/a.js'),
+     target: 'b.js',
+     { data: "data" }
+   );
+}
+```
+
+- 创建 EjsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### renderTemplate
+
+渲染单个模板文件。
+
+参数：
+
+- templateResource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
+- target: `string` 目标文件路径名称。
+- parameters?: `Record<string, string>` 渲染参数。
+
+### renderTemplateDir
+
+渲染模板文件夹。
+
+参数：
+
+- material: `FsMaterial` 当前微生成器执行的 material 上下文。
+- findGlob: `string` 模板文件匹配正则。
+- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
+- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
+
+```typescript
+type RenderTemplateDirOptions = {
+  nodir?: boolean;
+  dot?: boolean;
+  ignore?: string | readonly string[];
+};
+```

package/zh/guides/topic-detail/generator/codesmith/api/fs.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 3
+---
+
+# @modern-js/codesmith-api-fs
+
+微生成器中文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。FsAPI 通常用于处理二进制文件或者不能使用 handlebars、ejs 处理的模板文件。
+
+## 使用姿势
+
+```typescript
+import { FsAPI } from '@modern-js/codesmith-api-fs';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const handlebarApi = new HandlebarsAPI(generator);
+  await handlebarsAPI.renderFile(
+     material.get('templates/a.js'),
+     target: 'b.js'
+   );
+}
+```
+
+- 创建 FsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### renderFile
+
+渲染单个模板文件。
+
+参数：
+
+- resource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
+- target: `string` 目标文件路径名称。
+
+### renderDir
+
+渲染模板文件夹。
+
+参数：
+
+- material: `FsMaterial` 当前微生成器执行的 material 上下文。
+- findGlob: `string` 模板文件匹配正则。
+- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
+- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
+
+```typescript
+type RenderTemplateDirOptions = {
+  nodir?: boolean;
+  dot?: boolean;
+  ignore?: string | readonly string[];
+};
+```

package/zh/guides/topic-detail/generator/codesmith/api/git.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 4
+---
+
+# @modern-js/codesmith-api-git
+
+微生成器中使用 git 相关操作的 API 封装，提供判断 git 仓库，初始化及提交代码等方法。
+
+## 使用姿势
+
+```typescript
+import { GitAPI } from '@modern-js/codesmith-api-git';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const gitApi = new GitAPI(generatorCore, generatorContext);
+  await gitApi.initGitRepo();
+}
+```
+
+- 创建 GitAPI 实例，参数和微生成器函数参数一致，为 context 和 generator，具体介绍请看微生成器项目组成
+- 调用其实例上 API 即可。
+
+## API
+
+### isInGitRepo
+
+当前目录是否为 git 仓库。
+
+参数：
+
+- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。
+
+### initGitRepo
+
+初始化为 git 仓库。init 的默认分支名可通过生成器 config 中的 defaultBranch 进行配置。
+
+参数：
+
+- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。
+- force?: `boolean` 当前目录已经为 git 仓库时使用该参数会强制执行 git init。
+
+### addAndCommit
+
+执行 `git add .` 和 `git commit` 提交当前变更。
+
+参数：
+- commitMessage: `string` commit 信息。
+- cwd?: `string` git 命令的执行目录，默认为微生成器 `outputPath`。

package/zh/guides/topic-detail/generator/codesmith/api/handlebars.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 5
+---
+
+# @modern-js/codesmith-api-handlebars
+
+微生成器中使用 [handlebars](https://handlebarsjs.com/) 进行文件操作的 API 封装，提供渲染单个模板文件和文件夹的方法。
+
+## 使用姿势
+
+```typescript
+import { HandlebarsAPI } from '@modern-js/codesmith-api-handlebars';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const handlebarApi = new HandlebarsAPI(generator);
+  await handlebarsAPI.renderTemplate(
+     material.get('templates/a.js'),
+     target: 'b.js',
+     { data: "data" }
+   );
+}
+```
+
+- 创建 HandlebarsAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### renderTemplate
+
+渲染单个模板文件。
+
+参数：
+
+- templateResource: `FsResource` 模板文件资源，通过 `context.materials.get(<filename>)` 使用。
+- target: `string` 目标文件路径名称。
+- parameters?: `Record<string, string>` 渲染参数。
+
+### renderTemplateDir
+
+渲染模板文件夹。
+
+参数：
+
+- material: `FsMaterial` 当前微生成器执行的 material 上下文。
+- findGlob: `string` 模板文件匹配正则。
+- target: `(globMatch: string) => string` 目标文件路径生成函数，参数为 `resourceKey。`
+- options?: `RenderTemplateDirOptions` glob 查找文件配置，具体函数可查看这里 [glob](https://www.npmjs.com/package/glob)。
+
+```typescript
+type RenderTemplateDirOptions = {
+  nodir?: boolean;
+  dot?: boolean;
+  ignore?: string | readonly string[];
+};
+```

package/zh/guides/topic-detail/generator/codesmith/api/json.md

@@ -0,0 +1,58 @@
+---
+sidebar_position: 2
+---
+
+# @modern-js/codesmith-api-json
+
+微生成器中 JSON API 封装，提供常见的 JSON 文件操作方法。
+
+## 使用姿势
+
+```typescript
+import { JsonAPI } from '@modern-js/codesmith-api-json';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const jsonAPI = new JsonAPI(generator);
+  await jsonAPI.update(
+    context.materials.default.get('package.json'),
+    {
+      query: {},
+      update: {
+        $set: {
+          'dependencies.@modern-js/plugin-bff': `^2.0.0`,
+        },
+      },
+    },
+  );
+ }
+```
+
+- 创建 JsonAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看[微生成器项目组成](/docs/guides/topic-detail/generator/codesmith/structure)。
+- 调用其实例上 API 即可。
+
+## API
+
+### get
+
+获取 JSON 文件内容。
+
+参数：
+- resource: `FsResource`，文件资源，通过 `context.materials.default.get(<filename>)` 获取。
+
+### extend
+
+合并对象至 JSON 文件。
+
+参数：
+
+- resource: `FsResource` 通过 `context.materials.default.get(<filename>)` 获取。
+- obj: `Record<string, any>` 需合并对象。
+
+### update
+
+更新对象字段至 JSON 文件。
+
+参数：
+
+- resource: `FsResource` 通过 `context.materials.default.get(<filename>)` 获取。
+- operation: `{ query: Record<string, any>; update: Record<string, any> }` 更新操作，详细使用姿势查看 [declaration-update](https://www.npmjs.com/package/declaration-update)。

package/zh/guides/topic-detail/generator/codesmith/api/npm.md

@@ -0,0 +1,45 @@
+---
+sidebar_position: 7
+---
+
+# @modern-js/codesmith-api-npm
+
+微生成器中 NPM API 封装，提供常见的 NPM 不同包管理工具安装依赖的方法。
+
+## 使用姿势
+
+```typescript
+import { NpmAPI } from '@modern-js/codesmith-api-npm';
+
+export default async (context: GeneratorContext, generator: GeneratorCore) => {
+  const npmApi = new NpmAPI(generator);
+  await npmApi.pnpmInstall();
+}
+```
+
+- 创建 NpmAPI 实例，参数为微生成器函数参数的 generator，具体介绍请看微生成器项目组成 。
+- 调用其实例上 API 即可。
+
+## API
+
+### npmInstall
+
+使用 npm 安装依赖。
+
+参数：
+
+- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。
+
+### yarnInstall
+
+使用 yarn 安装依赖。
+
+参数：
+- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。
+
+### pnpmInstall
+
+使用 pnpm 安装依赖。
+
+参数：
+- cwd?: `string` install 命令的执行目录，默认为微生成器 `outputPath`。

package/zh/guides/topic-detail/generator/codesmith/develop.md

@@ -0,0 +1,52 @@
+---
+sidebar_position: 3
+---
+
+# 开发微生成器项目
+
+## 创建项目
+
+Modern.js 提供了创建微生成器项目的微生成器，可以直接通过以下命令创建微生成器项目：
+
+```bash
+$ mkdir <projectDir>
+$ npx @modern-js/codesmith-cli @modern-js/generator-generator
+
+? 请填写项目名称 <generatorName>
+? 请选择包管理工具 pnpm
+? 请选择开发语言 TS
+```
+
+## 添加模板文件
+
+在项目目录的 templates 文件夹，用于存放生成器需要的模板文件，如果没有模板文件，该步骤可跳过。
+
+## 开发生成器核心逻辑
+
+默认生成的的项目中，已经实现直接拷贝 templates 目录文件至目标项目，可直接在 `handleTemplateFile` 函数中完成生成器的核心逻辑开发。
+
+## 测试微生成器
+
+微生成器开发完成后，需要执行 `pnpm run build` 对代码进行编译，在开发模式下可以使用 `pnpm run build --watch`
+
+codesmith 提供了 cli 工具用于运行和测试微生成器，在目标目录执行使用如下命令执行即可：
+
+```bash
+npx @modern-js/codesmith-cli <generatorPath>
+```
+
+其中 generatorPath 为上述生成器项目的绝对路径。
+
+## 运行微生成器
+
+生成器发布 npm 包之后，使用如下命令执行：
+
+```bash
+npx @modern-js/codesmith-cli <generatorName>
+```
+
+其中 generatorName 为生成器包名。
+
+:::info
+`@modern-js/create` 也支持运行微生成器，可以使用 `npx @modern-js/create --generator <generatorName>` 运行自定义的微生成器。
+:::

package/zh/guides/topic-detail/generator/codesmith/introduce.md

@@ -2,4 +2,45 @@
 sidebar_position: 1
 ---
 
-# 介绍
+# 什么是微生成器
+
+Modern.js 提供了 `@modern-js/create` 工具和 `new` 命令分别用于初始化创建项目和提供开启一些插件功能的能力，这些工具都是基于微生成器也就是 codesmith 实现的。
+
+codesmith 致力于提供一套微生成器的运行机制，并维护微生成器执行过程中的上下文信息，从而实现各种基于文件、命令等操作，完成复杂的操作。
+
+codesmith 还将常用的方法进行了封装，可以直接使用其提供的 API 函数，可以更方便的实现自身的微生成器。
+
+## 核心概念
+
+### GeneratorCore
+
+GeneratorCore 是 codesmith 运行生成器的核心，维护这生成器执行过程中的上下文及运行方法。
+
+```typescript
+class GeneratorCore {
+  logger: ILogger; // 日志
+  materialsManager: MaterialsManager; // 资源
+  outputPath: string; // 输出路径
+  output: { // 输出方法
+    fs: (file: string | number, data: any, options?: fs.WriteFileOptions | string) => Promise<void>;
+  };
+  _context: GeneratorContext; // 上下文信息
+  addMaterial(key: string, material: FsMaterial): void; // 添加资源
+  runGenerator(generator: string, config?: Record<string, unknown>): Promise<void>; // 运行生成器
+  runSubGenerator(subGenerator: string, relativePwdPath?: string, config?: Record<string, any>): Promise<void>; // 运行子生成器
+}
+```
+
+### Materials
+
+微生成器资源信息，目前只包含文件资源(fsMaterials)，通过该字段可以获取到生成器执行过程中的 template 资源，并通过 API 对其进行操作。
+
+```typescript
+class MaterialsManager {
+  materialMap: { // 资源映射关系
+    [materialUri: string]: FsMaterial;
+  };
+  loadLocalGenerator(generator: string): Promise<FsMaterial>; // 加载本地生成器资源(绝对路径)
+  loadRemoteGenerator(generator: string): Promise<FsMaterial>; // 加载远程生成器资源(npm 包)
+}
+```

package/zh/guides/topic-detail/generator/codesmith/run-in-js.md

@@ -0,0 +1,48 @@
+---
+sidebar_position: 4
+---
+
+
+# 使用 JS 代码执行微生成器
+
+除了使用 cli 的方式执行微生成器，我们免不了需要在代码中执行微生成器，下面就介绍在 js 代码中如何执行微生成器。
+
+## 安装 codesmith 依赖
+
+```bash
+pnpm add @modern-js/codesmith
+```
+
+## 创建 codesmith 实例
+
+```typescript
+import { CodeSmith, Logger } from '@modern-js/codesmith';
+
+const smith = new CodeSmith({
+   debug: false, // 是否开启 debug 模式，为 true 时会展示生成器中的 debug 信息
+});
+```
+
+## 调用 forge 方法执行生成器
+
+```typescript
+type RunnerTask = Array<{
+  name: string;
+  config: Record<string, any>;
+}>;
+
+const task: RunnerTask = [
+  {
+    name: "generator", // 生成器 npm 包名称
+    config: {}, // 生成器执行的默认配置
+  },
+];
+
+await smith.forge({
+  tasks: task.map(runner => ({
+    generator: runner.name,
+    config: runner.config,
+  })),
+  pwd: '.', // 生成器执行路径
+});
+```