feat(rspeedy/core): add callerName option to createRspeedy (#757)

## Summary

Set the `callerName` option of `createRsbuild`, which can be accessed by
Rsbuild plugins through `api.context.callerName`.

See:

- web-infra-dev/rsbuild#5204
- web-infra-dev/rslib#974

## Checklist

<!--- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).

Author: colinaaa

.changeset/little-candies-carry.md

@@ -0,0 +1,22 @@
+---
+"@lynx-js/rspeedy": patch
+---
+
+Add `callerName` option to `createRspeedy`.
+
+It can be accessed by Rsbuild plugins through [`api.context.callerName`](https://rsbuild.dev/api/javascript-api/instance#contextcallername), and execute different logic based on this identifier.
+
+```js
+export const myPlugin = {
+  name: 'my-plugin',
+  setup(api) {
+    const { callerName } = api.context;
+
+    if (callerName === 'rslib') {
+      // ...
+    } else if (callerName === 'rspeedy') {
+      // ...
+    }
+  },
+};
+```

packages/rspeedy/core/etc/rspeedy.api.md

@@ -71,10 +71,11 @@ export interface Config {
 export type ConsoleType = 'log' | 'warn' | 'error' | 'info' | 'debug' | 'profile' | 'profileEnd' | (string & Record<never, never>);
 
 // @public
-export function createRspeedy({ cwd, rspeedyConfig, loadEnv, environment }: CreateRspeedyOptions): Promise<RspeedyInstance>;
+export function createRspeedy({ cwd, rspeedyConfig, loadEnv, environment, callerName, }: CreateRspeedyOptions): Promise<RspeedyInstance>;
 
 // @public
 export interface CreateRspeedyOptions {
+    callerName?: string;
     cwd?: string;
     environment?: CreateRsbuildOptions['environment'];
     loadEnv?: CreateRsbuildOptions['loadEnv'];

packages/rspeedy/core/src/create-rspeedy.ts

@@ -55,6 +55,43 @@ export interface CreateRspeedyOptions {
    * @defaultValue []
    */
   environment?: CreateRsbuildOptions['environment']
+
+  /**
+   * The name of the framework or tool that is currently invoking Rsbuild.
+   * This allows plugins to tailor their behavior based on the calling context.
+   *
+   * @example
+   *
+   * Rsbuild plugins can access this value via `api.context.callerName`.
+   *
+   * ```js
+   * export function myPlugin() {
+   *   return {
+   *     name: 'my-plugin',
+   *     setup(api) {
+   *       // Log the name of the tool invoking Rsbuild
+   *       console.log(`Called by: ${api.context.callerName}`);
+   *
+   *       // Conditionally apply plugin logic based on caller
+   *       if (api.context.callerName === 'rspeedy') {
+   *         api.modifyRsbuildConfig((config) => {
+   *           // Apply rspeedy-specific config changes
+   *           return config;
+   *         });
+   *       } else if (api.context.callerName === 'rslib') {
+   *         api.modifyRsbuildConfig((config) => {
+   *           // Apply rslib-specific config changes
+   *           return config;
+   *         });
+   *       }
+   *     }
+   *   };
+   * }
+   * ```
+   *
+   * @defaultValue 'rspeedy'
+   */
+  callerName?: string
 }
 /**
  * The `createRspeedy` method can let you create a Rspeedy instance and you can customize the build or development process in Node.js Runtime.
@@ -76,8 +113,13 @@ export interface CreateRspeedyOptions {
  * @public
  */
 export async function createRspeedy(
-  { cwd = process.cwd(), rspeedyConfig = {}, loadEnv = true, environment = [] }:
-    CreateRspeedyOptions,
+  {
+    cwd = process.cwd(),
+    rspeedyConfig = {},
+    loadEnv = true,
+    environment = [],
+    callerName = 'rspeedy',
+  }: CreateRspeedyOptions,
 ): Promise<RspeedyInstance> {
   const config = applyDefaultRspeedyConfig(rspeedyConfig)
 
@@ -87,6 +129,7 @@ export async function createRspeedy(
       loadEnv,
       rsbuildConfig: toRsbuildConfig(config) as RsbuildConfig,
       environment,
+      callerName,
     }),
     import('./plugins/index.js'),
   ])

packages/rspeedy/core/test/createRspeedy.test.ts

@@ -0,0 +1,48 @@
+// Copyright 2024 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import type { RsbuildPluginAPI } from '@rsbuild/core'
+import { describe, expect, test } from 'vitest'
+
+import { createRspeedy } from '../src/create-rspeedy.js'
+
+describe('createRspeedy', () => {
+  test('default callerName', async () => {
+    const rspeedy = await createRspeedy({
+      rspeedyConfig: {
+        plugins: [
+          {
+            name: 'test',
+            setup(api: RsbuildPluginAPI) {
+              expect(api.context.callerName).toBe('rspeedy')
+            },
+          },
+        ],
+      },
+    })
+
+    await rspeedy.initConfigs()
+
+    expect.assertions(1)
+  })
+
+  test('custom callerName', async () => {
+    const rspeedy = await createRspeedy({
+      callerName: 'my-custom-framework',
+      rspeedyConfig: {
+        plugins: [
+          {
+            name: 'test',
+            setup(api: RsbuildPluginAPI) {
+              expect(api.context.callerName).toBe('my-custom-framework')
+            },
+          },
+        ],
+      },
+    })
+
+    await rspeedy.initConfigs()
+
+    expect.assertions(1)
+  })
+})