@bepack/cli 0.1.0-beta.3 → 0.1.0-beta.5

package/README.md

@@ -31,6 +31,7 @@ BePack is a build tool for Minecraft Bedrock add-ons. It keeps behavior-pack and
 - Resolve supported `@minecraft/*` dependencies and write their concrete versions to your project.
 - Keep `manifest.json` in sync with a `preserve` (incremental) or `clean` (config-generated) merge strategy.
 - Copy packs into a Minecraft development folder and create release archives.
+- Inspect Bedrock `.cpuprofile` captures without counting idle tick gaps as CPU work.
 
 ## Requirements
 
@@ -178,7 +179,59 @@ bepack install --target 1.21.120
 bepack build --install --target 1.21.120
 ```
 
-> **Type checking runs by default.** Every `bepack build` and `bepack dev` executes `tsc --noEmit` before Rolldown bundles your source. A failing check stops the build with `TYPECHECK_FAILED` instead of emitting a broken pack. Skip it with `--skip-typecheck`, or set `packs.bp.compile.typecheck: false`. This is independent of any custom Rolldown options — adding them does **not** turn the type check off.
+> **Type checking runs by default.** Every `bepack build` and `bepack dev` type-checks your source before Rolldown bundles it, using `tsc --noEmit` unless you pick another checker. A failing check stops the build with `TYPECHECK_FAILED` instead of emitting a broken pack. Skip it with `--skip-typecheck`, or set `packs.bp.compile.typecheck: false`. This is independent of any custom Rolldown options — adding them does **not** turn the type check off.
+
+### Choose your type checker
+
+TypeScript checkers keep getting faster, so the checker is just a command line you supply — there is no preset list to keep up with:
+
+```ts
+export default defineConfig({
+    packs: {
+        bp: {
+            compile: {
+                entry: "src/main.ts",
+                // Anything you can type in a terminal. Default: "tsc --noEmit".
+                typecheckCommand: "bun check",
+                // typecheckCommand: "tsc-rs --noEmit",
+                // typecheckCommand: "npx tsc --noEmit",
+                // Quote-aware; backslash only escapes a quote, so Windows paths
+                // survive as written:
+                // typecheckCommand: 'node "C:\\tools\\my checker.mjs"',
+            },
+        },
+    },
+});
+```
+
+The same thing as an object, or per command from the CLI:
+
+```ts
+compile: {
+    // the switch and the command in one place
+    typecheck: { command: "bun check", args: ["--pretty"] },
+}
+```
+
+```bash
+bepack build --typecheck-command "bun check"
+bepack dev   --typecheck-command "tsc-rs --noEmit"
+bepack pack  --typecheck-command "npx tsc --noEmit"
+```
+
+Common choices, and what BePack runs:
+
+| You want | `typecheckCommand` |
+| --- | --- |
+| the default | *(leave it unset)* → `tsc --noEmit --project <tsconfig>` |
+| your project's TypeScript | `"npx tsc --noEmit"` |
+| Bun's fast checker | `"bun check"` (uses Bun's bundled TypeScript, not your pinned `typescript`) |
+| native TS port (Rust) | `"tsc-rs --noEmit"` |
+| Vue / Svelte | `"vue-tsc --noEmit"` / `"svelte-check"` |
+
+**Only the unset default (and deprecated `useNpx` compatibility settings) gets arguments added by BePack** (`--project <tsconfig>`, plus `--incremental`/`--tsBuildInfoFile` under `--cache`). Once you write a `command`, BePack adds nothing — spell out the tsconfig flag yourself if the tool needs one. `typecheck.args` is appended after your command.
+
+Precedence: CLI `--typecheck-command` > CLI `--use-npx` > `compile.typecheck.command` > `compile.typecheckCommand` > deprecated `compile.useNpx` > the `tsc` default. A CLI command replaces the configured `typecheckArgs` too, since args are usually command-specific. The deprecated `useNpx` settings keep the old behavior of passing the configured tsconfig and cache flags; writing `typecheckCommand: "npx tsc --noEmit"` is an explicit custom command and receives no automatic flags. Switching checkers does not disable checking — only `typecheck: false` or `--skip-typecheck` does.
 
 `stable`, `beta`, `preview`, and exact versions can be used for the supported `@minecraft/*` dependency entries. BePack resolves selectors such as `stable` to concrete package versions before updating `package.json` and the BP manifest.
 
@@ -249,6 +302,26 @@ bepack copy --target minecraft
 
 `gameRoot` writes behavior packs to `development_behavior_packs` and resource packs to `development_resource_packs`. You can also use a custom target when your BP and RP need separate destination paths. See the reference guide for the full target syntax.
 
+## Inspect Bedrock CPU profiles
+
+`/script profiler stop` writes a standard V8 `.cpuprofile`, but Bedrock does not sample idle time. The gap between ticks arrives as a large `timeDeltas` value on the first sample of the next tick, so treating deltas as CPU time makes `tick` look like the hottest function. `bepack profile` treats deltas above `--gap` (default `5` ms) as idle gaps and ranks functions by active samples.
+
+```bash
+# Overview, with bursts sorted by busy time
+bepack profile summary bedrock.cpuprofile
+
+# Spikes in time order, including intervals and top stacks
+bepack profile bursts bedrock.cpuprofile
+
+# Self or inclusive functions inside a time window
+bepack profile top bedrock.cpuprofile --from 2900 --to 2950 --by total
+
+# Compare two captures; falls back to whole active samples if one side has no burst
+bepack profile diff before.cpuprofile after.cpuprofile
+```
+
+Use `--json` for machine-readable output and `--root <dir>` to shorten source paths. A burst needs at least `--min-samples` active samples (default `20`). The command does not require a `bepack.config` file.
+
 ## Package releases
 
 Set an output name and directory with `pack`. `{name}` and `{version}` are replaced from the top-level config:
@@ -313,9 +386,10 @@ copy: { defaultTarget: "minecraft", optimize: true }
 | `bepack dev`              | Build once, then watch and rebuild (type checking on by default).                 |
 | `bepack copy`             | Copy configured packs to a development target.                                    |
 | `bepack pack`             | Build, then create a `.mcpack` or `.mcaddon` (`--no-build` to skip).              |
+| `bepack profile summary`  | Inspect Bedrock `.cpuprofile` captures and locate slow ticks. |
 | `bepack config --summary` | Inspect the resolved configuration.                                               |
 
-All commands accept `--cwd <project-dir>` and `--config <path>` when the current directory or config filename is different. Add `--dry-run` to preview file-writing commands, or `--json` for machine-readable output. Run `bepack <command> --help` for every command option.
+All project commands accept `--cwd <project-dir>` and `--config <path>` when the current directory or config filename is different. Add `--dry-run` to preview file-writing commands, or `--json` for machine-readable output. `bepack profile` accepts `--cwd` and `--root` but does not load a config. Run `bepack <command> --help` for every command option.
 
 ## More documentation
 

package/README.zh-CN.md

@@ -31,6 +31,7 @@ BePack 是 Minecraft 基岩版附加包的构建工具。它将行为包和资
 - 解析受支持的 `@minecraft/*` 依赖，并将具体版本写入项目。
 - 以 `preserve`（增量）或 `clean`（从配置生成）策略同步 `manifest.json`。
 - 将包复制到 Minecraft 开发目录，并生成发布压缩包。
+- 分析 Bedrock `.cpuprofile`，避免把 tick 之间的空闲 gap 当成 CPU 工作。
 
 ## 环境要求
 
@@ -178,7 +179,58 @@ bepack install --target 1.21.120
 bepack build --install --target 1.21.120
 ```
 
-> **类型检查默认开启。** 每次 `bepack build` / `bepack dev` 都会先用 `tsc --noEmit` 检查源码，再交给 Rolldown 打包。检查失败会以 `TYPECHECK_FAILED` 终止构建，而不是产出一个损坏的包。可用 `--skip-typecheck` 跳过，或设置 `packs.bp.compile.typecheck: false`。这与自定义 Rolldown 选项无关——加了自定义选项**不会**关闭类型检查。
+> **类型检查默认开启。** 每次 `bepack build` / `bepack dev` 都会先做类型检查（默认 `tsc --noEmit`，也可换成别的检查器），再交给 Rolldown 打包。检查失败会以 `TYPECHECK_FAILED` 终止构建，而不是产出一个损坏的包。可用 `--skip-typecheck` 跳过，或设置 `packs.bp.compile.typecheck: false`。这与自定义 Rolldown 选项无关——加了自定义选项**不会**关闭类型检查。
+
+### 自定义类型检查器
+
+市面上的 TS 检查器越来越多，所以检查器**就是一条你自己写的命令**，没有需要跟着维护的预设表：
+
+```ts
+export default defineConfig({
+    packs: {
+        bp: {
+            compile: {
+                entry: "src/main.ts",
+                // 终端里能敲的命令都行。默认是 "tsc --noEmit"。
+                typecheckCommand: "bun check",
+                // typecheckCommand: "tsc-rs --noEmit",
+                // typecheckCommand: "npx tsc --noEmit",
+                // 按引号分词；反斜杠只转义引号，所以 Windows 路径可以原样书写：
+                // typecheckCommand: 'node "C:\\tools\\my checker.mjs"',
+            },
+        },
+    },
+});
+```
+
+也可以写成对象形式，或在命令行临时指定：
+
+```ts
+compile: {
+    // 一个字段同时控制开关与命令
+    typecheck: { command: "bun check", args: ["--pretty"] },
+}
+```
+
+```bash
+bepack build --typecheck-command "bun check"
+bepack dev   --typecheck-command "tsc-rs --noEmit"
+bepack pack  --typecheck-command "npx tsc --noEmit"
+```
+
+常用选择与实际执行的命令：
+
+| 想用什么 | `typecheckCommand` |
+| --- | --- |
+| 默认 | *不配* → `tsc --noEmit --project <tsconfig>` |
+| 项目本地的 TypeScript | `"npx tsc --noEmit"` |
+| Bun 的快速检查 | `"bun check"`（用的是 Bun 自带的 TypeScript，不是项目里锁定的版本） |
+| 原生 TS 移植（Rust） | `"tsc-rs --noEmit"` |
+| Vue / Svelte | `"vue-tsc --noEmit"` / `"svelte-check"` |
+
+**只有"不配 command"的默认情况和旧 `useNpx` 兼容配置会被 BePack 附加参数**（`--project <tsconfig>`，以及 `--cache` 时的 `--incremental` / `--tsBuildInfoFile`）。你一旦写了 `command`，BePack 一个参数都不加——工具需要 tsconfig 就自己写进命令里。`typecheck.args` 追加在命令之后。
+
+优先级：CLI `--typecheck-command` > CLI `--use-npx` > `compile.typecheck.command` > `compile.typecheckCommand` > 已废弃的 `compile.useNpx` > 默认 `tsc`。用 CLI 指定命令时，配置里的 `typecheckArgs` 会被一并丢弃——这些参数通常是某条命令专属的。旧的 `useNpx` 配置仍保留原行为，会传入配置的 tsconfig 和缓存参数；而显式写 `typecheckCommand: "npx tsc --noEmit"` 属于自定义命令，不会自动追加参数。换检查器不等于关掉检查——只有 `typecheck: false` 或 `--skip-typecheck` 才会跳过。
 
 受支持的 `@minecraft/*` 依赖可使用 `stable`、`beta`、`preview` 或精确版本。BePack 会先把如 `stable` 这样的选择器解析为具体包版本，再更新 `package.json` 和 BP manifest。
 
@@ -249,6 +301,26 @@ bepack copy --target minecraft
 
 `gameRoot` 会将行为包复制到 `development_behavior_packs`，将资源包复制到 `development_resource_packs`。如果 BP 和 RP 需要不同的目标路径，可使用自定义目标；完整写法请见参考文档。
 
+## 分析 Bedrock CPU profile
+
+`/script profiler stop` 生成标准 V8 `.cpuprofile`，但 Bedrock 不为空闲时间采样。tick 之间的间隔会作为较大的 `timeDeltas` 挂在下一个 tick 的第一个采样点上，因此直接把 delta 当成 CPU 时间会让 `tick` 看起来是最热函数。`bepack profile` 会把大于 `--gap`（默认 `5` ms）的 delta 视为空闲 gap，并按 active 采样统计函数。
+
+```bash
+# 概览；burst 按 busy 时间倒序
+bepack profile summary bedrock.cpuprofile
+
+# 按时间顺序列出峰值、间隔和主要调用栈
+bepack profile bursts bedrock.cpuprofile
+
+# 查看时间窗口内的 self 或 inclusive 函数
+bepack profile top bedrock.cpuprofile --from 2900 --to 2950 --by total
+
+# 对比两次抓取；一侧没有 burst 时回退到整体 active 统计
+bepack profile diff before.cpuprofile after.cpuprofile
+```
+
+使用 `--json` 获取机器可读输出，使用 `--root <目录>` 缩短源码路径。burst 至少需要 `--min-samples` 个 active 采样（默认 `20`）。该命令不依赖 `bepack.config`。
+
 ## 打包发布
 
 通过 `pack` 设置输出名称和目录。`{name}` 和 `{version}` 会替换为顶层配置中的值：
@@ -313,9 +385,10 @@ copy: { defaultTarget: "minecraft", optimize: true }
 | `bepack dev`              | 先构建一次，随后监听并重建（类型检查默认开启）。              |
 | `bepack copy`             | 复制已配置的包到开发目标。                                    |
 | `bepack pack`             | 先构建，再生成 `.mcpack` 或 `.mcaddon`（`--no-build` 跳过构建）。 |
+| `bepack profile summary`  | 分析 Bedrock `.cpuprofile`，定位慢 tick。 |
 | `bepack config --summary` | 查看解析后的配置摘要。                                        |
 
-所有命令都支持 `--cwd <项目目录>` 和 `--config <路径>`，可用于在非项目目录执行或使用不同的配置文件名。对于会写入文件的命令，可添加 `--dry-run` 预览；如需机器可读输出，可添加 `--json`。使用 `bepack <命令> --help` 查看每个命令的全部参数。
+项目命令都支持 `--cwd <项目目录>` 和 `--config <路径>`，可用于在非项目目录执行或使用不同的配置文件名。对于会写入文件的命令，可添加 `--dry-run` 预览；如需机器可读输出，可添加 `--json`。`bepack profile` 支持 `--cwd` 和 `--root`，但不加载配置。使用 `bepack <命令> --help` 查看每个命令的全部参数。
 
 ## 更多文档