docs: add invalid compiler hook (#9003)

Author: chenjiahan

website/docs/en/api/javascript-api/compiler.mdx

@@ -19,10 +19,12 @@ import { Badge } from '@theme';
 Start a compilation, and callbacked when the compilation is completed or aborted due to an error.
 
 ```ts
-run(callback:  (
-  error: Error, // Only including compiler-related errors, such as configuration errors, not including compilation errors
-  stats: Stats, // detailed information generated during the compilation
-) => void): void;
+function run(
+  callback: (
+    error: Error, // Only including compiler-related errors, such as configuration errors, not including compilation errors
+    stats: Stats, // detailed information generated during the compilation
+  ) => void,
+): void;
 ```
 
 :::warning
@@ -56,9 +58,9 @@ compiler.run((err, stats) => {
 Watching files and directories, start a compilation process after they change, and callbacked every time the compilation is completed or aborted due to an error.
 
 ```ts
-watch(
+function watch(
   watchOptions: WatchOptions, // options for starting the watching
-  handler: (error: Error, stats: Stats) => void // callback when every compilation ends
+  handler: (error: Error, stats: Stats) => void, // callback when every compilation ends
 ): Watching; // watching controller
 ```
 
@@ -141,8 +143,8 @@ compile(
 Close the current compiler, and handle low-priority tasks such as caching during this period.
 
 ```ts
-close(
-  callback: (err: Error) => void // callback after closing
+function close(
+  callback: (err: Error) => void, // callback after closing
 ): void;
 ```
 
@@ -151,7 +153,7 @@ close(
 Create a [logger object](/api/javascript-api/logger) that is not associated with any compilation, which is used to print global logs.
 
 ```ts
-getInfrastructureLogger(name: string): Logger;
+function getInfrastructureLogger(name: string): Logger;
 ```
 
 <Collapse>
@@ -169,7 +171,7 @@ getInfrastructureLogger(name: string): Logger;
 Create a cache object to share data in the build process.
 
 ```ts
-getCache(name: string): CacheFacade;
+function getCache(name: string): CacheFacade;
 ```
 
 <Collapse>
@@ -183,20 +185,20 @@ getCache(name: string): CacheFacade;
 Stop the read loop of the input file system, which internally contains a timer and may cause the process to still not be able to exit after calling `compiler.close`.
 
 ```ts
-purgeInputFileSystem(): void;
+function purgeInputFileSystem(): void;
 ```
 
 ### createChildCompiler
 
 Allows running another instance of Rspack inside of Rspack. However, as a child with different settings and configurations applied. It copies all hooks and plugins from the parent (or top-level compiler) and creates a child `Compiler` instance. Returns the created `Compiler`.
 
 ```ts
-createChildCompiler(
+function createChildCompiler(
   compilation: Compilation,
   compilerName: string,
   compilerIndex: number,
   outputOptions: OutputOptions,
-  plugins: RspackPlugin[]
+  plugins: RspackPlugin[],
 ): Compiler;
 ```
 
@@ -233,7 +235,7 @@ createChildCompiler(
 Running the child compiler, which will doing a complete compiling and generate the assets.
 
 ```ts
-runAsChild(
+function runAsChild(
   callback(
     err: Error, // error related to the child compiler
     entries: Chunk[], // chunks generated by the child compiler
@@ -260,7 +262,7 @@ runAsChild(
 Whether this compiler is a child compiler.
 
 ```ts
-isChild(): boolean;
+function isChild(): boolean;
 ```
 
 ## Compiler properties

website/docs/en/api/plugin-api/compiler-hooks.mdx

@@ -424,6 +424,24 @@ Called if the compilation fails.
 
 - **Type:** `SyncHook<[Error]>`
 
+## `invalid`
+
+Executed when a watching compilation has been invalidated. This hook is not copied to child compilers.
+
+- **Type:** `SyncHook<[string | null, number]>`
+- **Arguments:**
+
+  - `fileName`: the file path of the invalid file
+  - `changeTime`: the change time of the invalid file
+
+When triggering a re-compilation, this hook can be used to get the changed file path and change time, for example:
+
+```ts
+compiler.hooks.invalid.tap('MyPlugin', (fileName, changeTime) => {
+  console.log(`Changed file: ${fileName}, change time: ${changeTime}`);
+});
+```
+
 ## `watchClose`
 
 Called when a watching compilation has stopped.

website/docs/zh/api/javascript-api/compiler.mdx

@@ -19,10 +19,12 @@ import { Badge } from '@theme';
 启动一次编译流程，编译流程完成或因错误中止时触发回调。
 
 ```ts
-run(callback:  (
-  error: Error, // 仅包含构建器相关错误，如配置错误等，不包含编译错误
-  stats: Stats, // 编译过程中产生的信息
-) => void): void;
+function run(
+  callback: (
+    error: Error, // 仅包含构建器相关错误，如配置错误等，不包含编译错误
+    stats: Stats, // 编译过程中产生的信息
+  ) => void,
+): void;
 ```
 
 :::warning
@@ -121,9 +123,9 @@ Watching 对象提供如下方法：
 创建 Compilation 并执行编译流程，是 `compiler.run` 和 `compiler.watch` 依赖的底层方法。
 
 ```ts
-compile(
-  callback: (compilation: Compilation) => void // 编译流程完成后回调
-): void
+function compile(
+  callback: (compilation: Compilation) => void, // 编译流程完成后回调
+): void;
 ```
 
 <Collapse>
@@ -141,8 +143,8 @@ compile(
 关闭当前构建器，在此期间处理低优先级任务，如缓存等。
 
 ```ts
-close(
-  callback: (err: Error) => void // 关闭完成后回调
+function close(
+  callback: (err: Error) => void, // 关闭完成后回调
 ): void;
 ```
 
@@ -151,7 +153,7 @@ close(
 创建一个不与 Compilation 关联的全局[日志对象](/api/javascript-api/logger)，用于打印全局信息。
 
 ```ts
-getInfrastructureLogger(name: string): Logger;
+function getInfrastructureLogger(name: string): Logger;
 ```
 
 <Collapse>
@@ -169,7 +171,7 @@ getInfrastructureLogger(name: string): Logger;
 创建一个缓存对象，以在构建流程中共享数据。
 
 ```ts
-getCache(name: string): CacheFacade;
+function getCache(name: string): CacheFacade;
 ```
 
 <Collapse>
@@ -183,20 +185,20 @@ getCache(name: string): CacheFacade;
 停止对文件系统的读取循环，它内部包含定时器，可能会导致 `compiler.close` 后进程依然无法退出。
 
 ```ts
-purgeInputFileSystem(): void;
+function purgeInputFileSystem(): void;
 ```
 
 ### createChildCompiler
 
 允许在 Rspack 中运行另一个 Rspack 实例。但是，子编译器会应用不同的设置和配置。他会从父 Compiler（或者顶级 Compiler）中复制所有的钩子（hook）和插件（plugin），并且创建一个子 Compiler 实例。 返回值为创建好的 Compiler 实例。
 
 ```ts
-createChildCompiler(
+function createChildCompiler(
   compilation: Compilation,
   compilerName: string,
   compilerIndex: number,
   outputOptions: OutputOptions,
-  plugins: RspackPlugin[]
+  plugins: RspackPlugin[],
 ): Compiler;
 ```
 
@@ -233,7 +235,7 @@ createChildCompiler(
 启动子 Compiler 的构建流程，会进行一次完整的构建流程并生成产物。
 
 ```ts
-runAsChild(
+function runAsChild(
   callback(
     err: Error, // 子 Compiler 执行的构建器错误
     entries: Chunk[], // 子 Compiler 执行产生的 Chunk 信息
@@ -260,7 +262,7 @@ runAsChild(
 当前是否为子 Compiler。
 
 ```ts
-isChild(): boolean;
+function isChild(): boolean;
 ```
 
 ## Compiler 对象属性

website/docs/zh/api/plugin-api/compiler-hooks.mdx

@@ -421,6 +421,23 @@ compilation 创建之后执行。
 
 - **类型：** `SyncHook<[Error]>`
 
+## `invalid`
+
+当监听模式下的编译因文件变更而失效时执行。这个 hook 不会被复制到 child compiler 中。
+
+- **类型：** `SyncHook<[string | null, number]>`
+- **参数：**
+  - `fileName`: 失效的文件路径
+  - `changeTime`: 失效的文件修改时间戳
+
+在触发重新编译时，这个 hook 可以用于获取变更的文件路径和修改时间，例如：
+
+```ts
+compiler.hooks.invalid.tap('MyPlugin', (fileName, changeTime) => {
+  console.log(`Changed file: ${fileName}, change time: ${changeTime}`);
+});
+```
+
 ## `watchClose`
 
 停止监听时调用。