wukong-profiler 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [杨琼]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# wukong-profiler
+
+🔥 High-performance Node/CLI profiler supporting:
+
+- Nested steps (true Flame Graph)
+- Chrome Trace export (`--trace trace.json`)
+- HOT step detection with CI failure
+- Profile diff for performance regression detection
+
+## Installation
+
+```bash
+npm install wukong-profiler
+```
+
+Or use directly via npx:
+
+```bash
+npx wukong-profiler [options]
+```
+
+---
+
+## CLI Usage
+
+```bash
+npx wukong-profiler --flame --trace trace.json --hot-threshold 0.8 --fail-on-hot
+```
+
+### Run profiler
+
+```bash
+# Simple run
+npx wukong-profiler --flame --trace trace.json
+
+# Set HOT threshold
+npx wukong-profiler --hot-threshold 0.8 --fail-on-hot
+
+# With baseline profile for regression detection
+npx wukong-profiler --diff-base baseline.json --diff-threshold 0.2
+```
+
+### Generate HTML report
+
+```bash
+# Generate HTML report from profile.json
+npx wukong-profiler report ./profile.json
+
+# Generate and open automatically in browser
+npx wukong-profiler report ./profile.json --open
+
+# Specify output HTML file
+npx wukong-profiler report ./profile.json -o my-report.html
+```
+
+**Options:**
+
+| Option                 | Description                                             |
+| ---------------------- | ------------------------------------------------------- |
+| `--profile`            | Save profile JSON for analysis                          |
+| `--flame`              | Display flame-like console output                       |
+| `--trace <file>`       | Export Chrome Trace JSON file                           |
+| `--hot-threshold <n>`  | HOT step threshold (default: 0.8)                       |
+| `--fail-on-hot`        | Exit with non-zero code if a HOT step exceeds threshold |
+| `--diff-base <file>`   | Compare current profile with baseline for regression    |
+| `--diff-threshold <n>` | Diff threshold for regression (default: 0.2)            |
+| `-v, --version`        | Show version                                            |
+| `-h, --help`           | Show help                                               |
+
+---
+
+## Programmatic Usage
+
+```js
+import { createProfiler } from 'wukong-profiler'
+
+const profiler = createProfiler({
+  enabled: true,
+  flame: true,
+  traceFile: 'trace.json',
+  hotThreshold: 0.8,
+  failOnHot: true,
+  diffBaseFile: 'baseline.json',
+  diffThreshold: 0.2
+})
+
+profiler.step('load data', () => {
+  // heavy operation
+})
+profiler.step('process data', () => {
+  // another heavy operation
+})
+
+profiler.end('Total')
+```
+
+---
+
+## API Reference
+
+### `createProfiler(options)`
+
+Returns a profiler instance.
+
+#### Options
+
+| Name            | Default     | Description                 |
+| --------------- | ----------- | --------------------------- |
+| `enabled`       | `false`     | Enable output & JSON export |
+| `verbose`       | `false`     | Verbose logging             |
+| `flame`         | `false`     | Flame-style tree output     |
+| `slowThreshold` | `500`       | Slow step threshold (ms)    |
+| `hotThreshold`  | `0.8`       | HOT step ratio              |
+| `traceFile`     | `undefined` | Chrome trace file           |
+| `failOnHot`     | `false`     | Fail CI on HOT step         |
+| `diffBaseFile`  | `undefined` | Base profile for diff       |
+| `diffThreshold` | `0.2`       | Regression threshold        |
+
+---
+
+### `profiler.step(name, fn)`
+
+Measure a synchronous step.
+
+---
+
+### `profiler.measure(name, fn)`
+
+Measure sync or async function.
+
+---
+
+### `profiler.end(label?)`
+
+Finish profiling and output results.
+
+---
+
+## Examples
+
+```bash
+node examples/basic.mjs
+node examples/flame.mjs
+node examples/async.mjs
+```
+
+---
+
+## Chrome Trace
+
+```bash
+node examples/basic.mjs
+chrome://tracing
+```
+
+Load the generated trace file.
+
+or
+
+```text
+https://ui.perfetto.dev
+```
+
+drag to Load the generated trace file.
+
+---
+
+### 📊 Profile Summary (Top HOT Paths)
+
+````js
+const summary = profiler.summary({ top: 3 });
+
+summary.top.forEach(step => {
+  console.log(step.path, step.ratio);
+});
+
+---
+
+## API Usage
+
+```js
+import { createProfiler } from 'wukong-profiler'
+
+const profiler = createProfiler({ enabled: true, flame: true })
+
+// Measure a function
+await profiler.measure('heavyTask', async () => {
+  await doHeavyWork()
+})
+
+// Nested steps
+await profiler.measure('outer', async () => {
+  await profiler.measure('inner1', task1)
+  await profiler.measure('inner2', task2)
+})
+
+const { total, events, exitCode } = profiler.end('Total')
+console.log('Total time:', total, 'ms')
+````
+
+- `measure(name, fn)` : measure a function (sync/async)
+- `step(name)` : manually log a step
+- `end(label)` : end profiling, optionally export Chrome Trace JSON
+
+---
+
+**Features:**
+
+- Nested steps for Flame Graph visualization
+- Slow steps (> threshold) marked as HOT 🔥
+- Automatic exit code for CI if HOT steps detected
+- Chrome Trace export compatible with Chrome's `chrome://tracing`
+- Profile diff for performance regression detection
+
+## 🔍 关键词
+
+<!--
+Node.js profiler, JavaScript profiler, Node performance analysis, CLI profiler,
+Flame Graph, Flame Chart, Chrome Trace, Chrome tracing, Perfetto,
+Performance regression detection, Profile diff, CI performance check,
+HOT path detection, Slow function detection,
+Async performance profiling, Nested performance steps,
+Node.js benchmarking, Build performance monitoring,
+Developer tooling, DevOps performance, Continuous Integration profiling
+-->

package/README.zh.md

@@ -0,0 +1,242 @@
+# wukong-profiler
+
+🔥 **高性能 Node / CLI 性能分析器（Profiler）**，支持：
+
+- ✅ **真正的嵌套步骤**（真实 Flame Graph 结构）
+
+- ✅ **Chrome Trace 导出**（`--trace trace.json`）
+
+- ✅ **HOT 步骤检测**（支持 CI 直接失败）
+
+- ✅ **Profile Diff**（用于性能回退 / 回归检测）
+
+---
+
+## 安装
+
+```bash
+npm install wukong-profiler
+```
+
+或直接使用 `npx`：
+
+```bash
+npx wukong-profiler [options]
+```
+
+---
+
+## CLI 使用方式
+
+```bash
+npx wukong-profiler --flame --trace trace.json --hot-threshold 0.8 --fail-on-hot
+```
+
+### 运行 Profiler
+
+```bash
+# 简单运行
+npx wukong-profiler --flame --trace trace.json
+
+# 设置 HOT 阈值
+npx wukong-profiler --hot-threshold 0.8 --fail-on-hot
+
+# 使用基准 profile 检测性能回归
+npx wukong-profiler --diff-base baseline.json --diff-threshold 0.2
+```
+
+### 生成 HTML 报告
+
+````bash
+# 从 profile.json 生成 HTML 报告
+npx wukong-profiler report ./profile.json
+
+# 生成并自动在浏览器打开
+npx wukong-profiler report ./profile.json --open
+
+# 指定输出 HTML 文件
+npx wukong-profiler report ./profile.json -o my-report.html
+
+### CLI 参数说明
+
+| 参数                   | 说明                                          |
+| ---------------------- | --------------------------------------------- |
+| `--profile`            | 保存 profile JSON 文件，用于后续分析          |
+| `--flame`              | 在控制台输出 Flame 风格的树状结果             |
+| `--trace <file>`       | 导出 Chrome Trace JSON 文件                   |
+| `--hot-threshold <n>`  | HOT 步骤占比阈值（默认：0.8）                 |
+| `--fail-on-hot`        | 如果存在 HOT 步骤，进程以非 0 退出（CI 失败） |
+| `--diff-base <file>`   | 与基准 profile 对比，检测性能回退             |
+| `--diff-threshold <n>` | 性能回退阈值（默认：0.2）                     |
+| `-v, --version`        | 显示版本号                                    |
+| `-h, --help`           | 显示帮助信息                                  |
+
+---
+
+## 编程方式（Programmatic Usage）
+
+```js
+import { createProfiler } from 'wukong-profiler'
+
+const profiler = createProfiler({
+  enabled: true,
+  flame: true,
+  traceFile: 'trace.json',
+  hotThreshold: 0.8,
+  failOnHot: true,
+  diffBaseFile: 'baseline.json',
+  diffThreshold: 0.2
+})
+
+profiler.step('加载数据', () => {
+  // 重任务
+})
+
+profiler.step('处理数据', () => {
+  // 另一个重任务
+})
+
+profiler.end('总耗时')
+````
+
+---
+
+## API 文档
+
+### `createProfiler(options)`
+
+创建并返回一个 profiler 实例。
+
+#### Options 参数说明
+
+| 参数名          | 默认值      | 说明                             |
+| --------------- | ----------- | -------------------------------- |
+| `enabled`       | `false`     | 是否启用 profiler（输出 & JSON） |
+| `verbose`       | `false`     | 输出更详细的日志                 |
+| `flame`         | `false`     | 输出 Flame 风格的树结构          |
+| `slowThreshold` | `500`       | 慢步骤阈值（毫秒）               |
+| `hotThreshold`  | `0.8`       | HOT 步骤占比阈值                 |
+| `traceFile`     | `undefined` | Chrome Trace 输出文件            |
+| `failOnHot`     | `false`     | 检测到 HOT 步骤时 CI 失败        |
+| `diffBaseFile`  | `undefined` | 用于 diff 的基准 profile         |
+| `diffThreshold` | `0.2`       | 性能回退阈值                     |
+
+---
+
+### `profiler.step(name, fn)`
+
+测量一个 **同步步骤**。
+
+---
+
+### `profiler.measure(name, fn)`
+
+测量一个 **同步或异步函数**。
+
+---
+
+### `profiler.end(label?)`
+
+结束 profiling，并输出最终结果。
+
+---
+
+## 示例
+
+```bash
+node examples/basic.mjs
+node examples/flame.mjs
+node examples/async.mjs
+```
+
+---
+
+## Chrome Trace 使用方式
+
+```bash
+node examples/basic.mjs
+```
+
+然后在浏览器中打开：
+
+```text
+chrome://tracing
+```
+
+加载生成的 trace 文件。
+
+或使用 Perfetto（推荐）：
+
+```text
+https://ui.perfetto.dev
+```
+
+将生成的 trace 文件拖入即可查看。
+
+---
+
+### 📊 性能摘要（Top HOT 路径）
+
+```js
+const summary = profiler.summary({ top: 3 })
+```
+
+---
+
+## API 使用示例
+
+```js
+import { createProfiler } from 'wukong-profiler'
+
+const profiler = createProfiler({ enabled: true, flame: true })
+
+// 测量函数
+await profiler.measure('heavyTask', async () => {
+  await doHeavyWork()
+})
+
+// 嵌套步骤
+await profiler.measure('outer', async () => {
+  await profiler.measure('inner1', task1)
+  await profiler.measure('inner2', task2)
+})
+
+const { total, events, exitCode } = profiler.end('Total')
+console.log('总耗时:', total, 'ms')
+```
+
+### API 说明
+
+- `measure(name, fn)`：测量函数（支持 sync / async）
+
+- `step(name)`：手动记录一个步骤
+
+- `end(label)`：结束 profiling，可导出 Chrome Trace
+
+---
+
+## 核心特性总结
+
+- 🔥 **支持嵌套步骤**，天然适合 Flame Graph
+
+- 🔥 **慢步骤 / HOT 步骤自动标记**
+
+- 🔥 **CI 友好**：性能问题可直接让构建失败
+
+- 🔥 **Chrome Trace 导出**，可视化精确到毫秒
+
+- 🔥 **Profile Diff**，用于性能回退检测
+
+---
+
+## 🔍 Keywords
+
+<!--
+Node.js profiler, JavaScript profiler, Node performance analysis, CLI profiler,
+Flame Graph, Flame Chart, Chrome Trace, Chrome tracing, Perfetto,
+Performance regression detection, Profile diff, CI performance check,
+HOT path detection, Slow function detection,
+Async performance profiling, Nested performance steps,
+Node.js benchmarking, Build performance monitoring,
+Developer tooling, DevOps performance, Continuous Integration profiling
+-->

package/bin/wukong-profiler

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import chalk from 'chalk'
+import { Command } from 'commander'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import open from "open"; 
+
+import { generateReport } from '../src/report.mjs'
+import { formatTime } from '../src/utils/format.mjs'
+import { createProfiler } from '../src/utils/profiler.mjs'
+
+// 获取 package.json 的版本号
+// 兼容 Windows
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const pkgPath = path.resolve(__dirname, '../package.json')
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+
+const program = new Command()
+
+program
+  .name('wukong-profiler')
+  .description(
+    '🔥 Node/CLI profiler with flame graph, Chrome Trace and HOT detection'
+  )
+  .version(pkg.version, '-v, --version', 'show version')
+
+/* ------------------------------
+   profile / runtime options
+--------------------------------*/
+
+program
+  .option('--profile', 'save profile.json')
+  .option('--flame', 'flame-like console output')
+  .option('--trace <file>', 'Chrome Trace export file')
+  .option('--hot-threshold <n>', 'HOT step threshold', parseFloat, 0.8)
+  .option('--fail-on-hot', 'exit with non-zero if HOT step detected')
+  .option('--diff-base <file>', 'baseline profile for regression check')
+  .option('--diff-threshold <n>', 'regression diff threshold', parseFloat, 0.2)
+
+/* ------------------------------
+   report subcommand
+--------------------------------*/
+
+program
+  .command('report <profile>')
+  .description('📊 Generate HTML report from profile.json')
+  .option('-o, --output <file>', 'output html file', 'wukong-report.html')
+  .option('--open', 'open the report in default browser after generation')
+  .action((profile, options) => {
+    // options 就是最后一个参数，包含 output
+    const output = options.output
+
+    // TODO: remove debug log before production
+    console.log('✅', 'output', output)
+
+    if (!fs.existsSync(profile)) {
+      console.error(`❌ profile file not found: ${profile}`)
+      process.exit(1)
+    }
+
+    const json = JSON.parse(fs.readFileSync(profile, 'utf-8'))
+
+    const html = generateReport(json)
+    fs.writeFileSync(output, html, 'utf8')
+
+    console.log(`✅ report generated: ${output}`)
+    if (options.open) {
+      open(output)
+        .then(() => console.log(`🌐 report opened in browser`))
+        .catch((err) => console.error('❌ failed to open report', err))
+    }
+  })
+
+program.parse(process.argv)
+
+const opts = program.opts()
+
+const profiler = createProfiler({
+  enabled: opts.profile || opts.flame || !!opts.trace || !!opts.diffBase,
+  flame: opts.flame,
+  traceFile: opts.trace,
+  hotThreshold: opts.hotThreshold,
+  failOnHot: opts.failOnHot,
+  diffBaseFile: opts.diffBase,
+  diffThreshold: opts.diffThreshold
+})
+
+console.log(chalk.green('🔥 Wukong Profiler CLI started'))
+console.log(
+  chalk.gray('Use profiler.step(name, fn) in your code or CLI script')
+)
+
+// 输出 total 计时信息
+process.on('exit', () => {
+  const profile = profiler.end('Total')
+  console.log(
+    chalk.cyan('Profiler finished. Total:'),
+    formatTime(profile.total)
+  )
+})

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "wukong-profiler",
+  "version": "1.0.0",
+  "description": "🔥 高性能 CLI/Node Profiler，支持 Flame Graph、Chrome Trace、HOT 步骤检测、性能回归分析",
+  "keywords": [
+    "profiler",
+    "flamegraph",
+    "node",
+    "cli",
+    "performance",
+    "hotstep",
+    "chrome-trace",
+    "ci"
+  ],
+  "homepage": "https://tomatobybike.github.io/md-structure/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tomatobybike/md-structure"
+  },
+  "license": "MIT",
+  "author": "Tom <tomatobybike@gmail.com>",
+  "type": "module",
+  "imports": {
+    "#src/*": "./src/*",
+    "#utils/*": "src/utils/*",
+    "source-map": "./test/__mocks__/source-map.mjs"
+  },
+  "main": "src/index.mjs",
+  "bin": {
+    "wukong-profiler": "./bin/wukong-profiler"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "README.zh.md"
+  ],
+  "scripts": {
+    "async-example": "node examples/async.mjs",
+    "basic-example": "node examples/basic.mjs",
+    "check:npm:login": "node scripts/check-npm-login.mjs",
+    "flame-example": "node examples/flame.mjs",
+    "format": "prettier --write \"src/**/*.{js,mjs}\"",
+    "lint": "eslint src --ext .js,.mjs src",
+    "lint:fix": "eslint src --ext .js,.mjs --fix",
+    "pack": "npm pack",
+    "prepare": "husky install",
+    "prepublishOnly": "yarn lint",
+    "prettierall": "npx prettier --write 'src/**/*.{js,jsx}'",
+    "push:tags": "git push origin main --follow-tags",
+    "prerelease": "yarn lint",
+    "release": "yarn check:npm:login  && npm publish && yarn push:tags",
+    "release:rollback": "git reset --hard HEAD~1 && git tag -d $(git tag --points-at HEAD~1)",
+    "release:major": "yarn lint && standard-version --release-as major",
+    "release:minor": "yarn lint && standard-version --release-as minor",
+    "release:patch": "yarn lint && standard-version --release-as patch",
+    "report": "wukong-profiler report ./profile.json -o my-report.html --open",
+    "sort": "sort-package-json",
+    "test": "node --test"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "package.json": [
+      "sort-package-json"
+    ],
+    "src/**/*.js": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.0.0",
+    "open": "^11.0.0"
+  },
+  "devDependencies": {
+    "@trivago/prettier-plugin-sort-imports": "5.2.2",
+    "eslint": "8.57.1",
+    "eslint-config-airbnb-base": "15.0.0",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-import-resolver-alias": "1.1.2",
+    "eslint-plugin-import": "2.32.0",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-simple-import-sort": "12.1.1",
+    "husky": "9.1.7",
+    "lint-staged": "16.2.7",
+    "prettier": "3.6.2",
+    "prettier-plugin-packagejson": "2.5.19",
+    "sort-package-json": "3.4.0",
+    "standard-version": "9.5.0"
+  },
+  "packageManager": "yarn@1.22.22",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/api/testFunction.js

@@ -0,0 +1,56 @@
+// testFunction.mjs
+import { measure, createProfiler } from 'wukong-profiler'
+import fs from 'fs'
+
+// 创建 Profiler，可全局配置
+const profiler = createProfiler({
+  enabled: true,
+  verbose: true,
+  flame: true,
+  trace: 'trace.json',
+  hotThreshold: 0.8,
+  failOnHot: true
+})
+
+// 被测试函数
+function heavyComputation(n) {
+  let sum = 0
+  for (let i = 0; i < n * 1e6; i++) sum += i
+  return sum
+}
+
+function nestedComputation(n) {
+  return measure('nestedComputation', () => {
+    const a = measure('heavyComputation', () => heavyComputation(n))
+    const b = measure('heavyComputation_half', () => heavyComputation(n / 2))
+    return a + b
+  })
+}
+
+// === 测试入口 ===
+measure('Test: heavyComputation', () => heavyComputation(5))
+measure('Test: nestedComputation', () => nestedComputation(3))
+
+// 完成并输出总耗时
+const result = profiler.end('Total Test')
+
+// 输出 Chrome Trace
+if (profiler.traceFile) {
+  const traceEvents = result.events.map(ev => ({
+    name: ev.name,
+    ph: 'X',
+    ts: Math.round(ev.sinceStart * 1000), // μs
+    dur: Math.round(ev.duration * 1000),  // μs
+    pid: 1,
+    tid: 1
+  }))
+  fs.writeFileSync(profiler.traceFile, JSON.stringify({ traceEvents }, null, 2))
+  console.log(`Chrome Trace 已生成: ${profiler.traceFile}`)
+}
+
+// HOT 步骤触发 CI 非零退出码
+const anyHot = result.events.some(ev => ev.hot)
+if (anyHot && profiler.failOnHot) {
+  console.error('🔥 HOT step detected! Exiting with code 1.')
+  process.exit(1)
+}

package/src/index.mjs

@@ -0,0 +1,12 @@
+import { createProfiler } from './utils/profiler.mjs'
+import { formatTime, makeBar } from './utils/format.mjs'
+import { exportChromeTrace } from './utils/trace.mjs'
+import { diffProfiles } from './utils/diff.mjs'
+
+export {
+  createProfiler,
+  formatTime,
+  makeBar,
+  exportChromeTrace,
+  diffProfiles
+}

package/src/report.mjs

@@ -0,0 +1,50 @@
+// report.mjs
+export const generateReport = (profile) => {
+  const rows = profile.events.map(e => `
+    <tr class="${e.duration / profile.total > 0.8 ? 'hot' : ''}">
+      <td>${e.name}</td>
+      <td>${e.duration.toFixed(2)} ms</td>
+      <td>${((e.duration / profile.total) * 100).toFixed(1)}%</td>
+      <td>${
+        e.source
+          ? e.source.original
+            ? `${e.source.original.source}:${e.source.original.line}`
+            : `${e.source.file}:${e.source.line}`
+          : ''
+      }</td>
+    </tr>`).join('')
+
+  const html = `<!doctype html>
+<html>
+<head>
+<meta charset="utf-8"/>
+<title>Wukong Profiler Report</title>
+<style>
+body { font-family: system-ui; padding: 20px; }
+table { border-collapse: collapse; width: 100%; }
+th, td { padding: 8px; border-bottom: 1px solid #eee; }
+.hot { background: #ffe5e5; }
+</style>
+</head>
+<body>
+<h1>🔥 Wukong Profiler Report</h1>
+<p>Total: ${profile.total.toFixed(2)} ms</p>
+
+<table>
+<thead>
+<tr>
+  <th>Step</th>
+  <th>Duration</th>
+  <th>Ratio</th>
+  <th>Source</th>
+</tr>
+</thead>
+<tbody>
+${rows}
+</tbody>
+</table>
+</body>
+</html>`
+
+  return html
+}

package/src/utils/diff.mjs

@@ -0,0 +1,21 @@
+export const diffProfiles = (prev, curr, threshold = 0.2) => {
+  const map = new Map()
+  prev.events.forEach(e => map.set(e.name, e.duration))
+  const regressions = []
+
+  curr.events.forEach(e => {
+    const before = map.get(e.name)
+    if (!before) return
+    const diff = (e.duration - before) / before
+    if (diff >= threshold) {
+      regressions.push({
+        name: e.name,
+        before,
+        after: e.duration,
+        diff
+      })
+    }
+  })
+
+  return regressions
+}

package/src/utils/format.mjs

@@ -0,0 +1,11 @@
+export const formatTime = (ms) => {
+  if (ms < 1) return `${(ms * 1000).toFixed(2)} μs`
+  if (ms < 1000) return `${ms.toFixed(2)} ms`
+  if (ms < 60000) return `${(ms / 1000).toFixed(2)} s`
+  return `${(ms / 60000).toFixed(2)} min`
+}
+
+export const makeBar = (ratio, width = 32) => {
+  const len = Math.max(1, Math.round(ratio * width))
+  return '█'.repeat(len)
+}

package/src/utils/profiler.mjs

@@ -0,0 +1,281 @@
+import chalk from 'chalk'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+import { diffProfiles } from './diff.mjs'
+import { formatTime, makeBar } from './format.mjs'
+import { exportChromeTrace } from './trace.mjs'
+
+/* ----------------------------------
+   Optional sourcemap resolver
+----------------------------------- */
+let SourceMapConsumer = null
+try {
+  // optional dependency
+  const sm = await import('source-map')
+  SourceMapConsumer = sm.SourceMapConsumer
+} catch {
+  // ignore – sourcemap is optional
+}
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+export const createProfiler = ({
+  enabled = false,
+  verbose = false,
+  flame = false,
+  slowThreshold = 500,
+  hotThreshold = 0.8,
+  traceFile,
+  failOnHot = false,
+  diffBaseFile,
+  diffThreshold = 0.2,
+  captureSource = true // 🔥 new
+} = {}) => {
+  const start = process.hrtime.bigint()
+  const stack = []
+  const events = []
+
+  const toMs = (a, b) => Number(b - a) / 1e6
+
+  /* ----------------------------------
+     Stack + sourcemap capture
+  ----------------------------------- */
+  const captureSourceInfo = async () => {
+    const err = new Error()
+    const frames = err.stack
+      ?.split('\n')
+      .slice(2)
+      .map((l) => l.trim())
+
+    if (!frames?.length) return null
+
+    const top = frames[0]
+
+    const match =
+      top.match(/\((.*):(\d+):(\d+)\)/) ||
+      top.match(/at (.*):(\d+):(\d+)/)
+
+    if (!match) return { raw: top }
+
+    const [, file, line, column] = match
+    const source = {
+      file,
+      line: Number(line),
+      column: Number(column)
+    }
+
+    if (!captureSource || !SourceMapConsumer) return source
+
+    try {
+      const mapFile = `${file}.map`
+      if (!fs.existsSync(mapFile)) return source
+
+      const rawMap = JSON.parse(fs.readFileSync(mapFile, 'utf8'))
+      const consumer = await new SourceMapConsumer(rawMap)
+
+      const pos = consumer.originalPositionFor({
+        line: source.line,
+        column: source.column
+      })
+
+      consumer.destroy?.()
+
+      if (pos?.source) {
+        return {
+          ...source,
+          original: {
+            source: pos.source,
+            line: pos.line,
+            column: pos.column,
+            name: pos.name
+          }
+        }
+      }
+    } catch {
+      /* silent */
+    }
+
+    return source
+  }
+
+  /* ----------------------------------
+     STEP / MEASURE
+  ----------------------------------- */
+  const step = (name, fn) => {
+    const parent = stack[stack.length - 1]
+    const startTime = process.hrtime.bigint()
+
+    const node = {
+      name,
+      start: toMs(start, startTime),
+      duration: 0,
+      depth: stack.length,
+      children: [],
+      source: null
+    }
+
+    if (parent) parent.children.push(node)
+    stack.push(node)
+
+    const finish = async () => {
+      const endTime = process.hrtime.bigint()
+      node.duration = toMs(startTime, endTime)
+      events.push(node)
+      stack.pop()
+
+      const totalSoFar = toMs(start, endTime)
+      const isSlow = node.duration >= slowThreshold
+      const isHot = totalSoFar > 0 && node.duration / totalSoFar >= hotThreshold
+
+      if ((isSlow || isHot) && captureSource) {
+        node.source = await captureSourceInfo()
+      }
+    }
+
+    try {
+      const result = fn?.()
+      if (result && typeof result.then === 'function') {
+        return result.finally(finish)
+      }
+      finish()
+      return result
+    } catch (err) {
+      finish()
+      throw err
+    }
+  }
+
+  const measure = (name, fn) => step(name, fn)
+
+  /* ----------------------------------
+     END
+  ----------------------------------- */
+  const end = (label = 'Total') => {
+    const total = toMs(start, process.hrtime.bigint())
+
+    let hasHot = false
+    for (const e of events) {
+      if (e.duration / total >= hotThreshold) {
+        hasHot = true
+      }
+    }
+
+    if (enabled || verbose) {
+      console.log(
+        chalk.cyan('⏱'),
+        chalk.bold(label),
+        chalk.yellow(formatTime(total))
+      )
+
+      if (flame) {
+        for (const e of events) {
+          const ratio = e.duration / total
+          const hot = ratio >= hotThreshold
+          const slow = e.duration >= slowThreshold
+
+          console.log(
+            chalk.gray(`${'  '.repeat(e.depth)}├─`),
+            chalk.white(e.name.padEnd(22)),
+            chalk.yellow(formatTime(e.duration)),
+            chalk.gray(makeBar(ratio)),
+            hot
+              ? chalk.red.bold(' 🔥 HOT')
+              : slow
+                ? chalk.yellow(' ⚠ SLOW')
+                : ''
+          )
+
+          if ((hot || slow) && e.source) {
+            console.log(
+              chalk.gray(
+                `     ↳ ${e.source.original?.source || e.source.file}:${
+                  e.source.original?.line || e.source.line
+                }`
+              )
+            )
+          }
+        }
+      }
+    }
+
+    const profile = { total, events }
+
+    if (traceFile) exportChromeTrace(events, traceFile)
+
+    if (diffBaseFile && fs.existsSync(diffBaseFile)) {
+      const base = JSON.parse(fs.readFileSync(diffBaseFile, 'utf8'))
+      const regressions = diffProfiles(base, profile, diffThreshold)
+
+      if (regressions.length) {
+        if (enabled || verbose) {
+          console.log(chalk.red('\n⚠ Performance Regression Detected:\n'))
+          regressions.forEach((r) =>
+            console.log(
+              chalk.red(
+                `  ${r.name}: ${formatTime(r.before)} → ${formatTime(
+                  r.after
+                )} (+${(r.diff * 100).toFixed(1)}%)`
+              )
+            )
+          )
+        }
+        process.exitCode = 1
+      }
+    }
+
+    if (enabled) {
+      fs.writeFileSync('profile.json', JSON.stringify(profile, null, 2))
+    }
+
+    if (failOnHot && hasHot) {
+      if (enabled || verbose) {
+        console.log(chalk.red('\n🔥 HOT step detected — failing CI'))
+      }
+      process.exitCode = 1
+    }
+
+    return profile
+  }
+
+  /* ----------------------------------
+     SUMMARY
+  ----------------------------------- */
+  const flatten = (nodes, parentPath = []) => {
+    let res = []
+    for (const n of nodes) {
+      const pathArr = [...parentPath, n.name]
+      res.push({
+        name: n.name,
+        path: pathArr.join(' → '),
+        duration: n.duration,
+        depth: n.depth,
+        source: n.source
+      })
+      if (n.children?.length) {
+        res = res.concat(flatten(n.children, pathArr))
+      }
+    }
+    return res
+  }
+
+  // eslint-disable-next-line no-shadow
+  const summary = ({ top = 5, hotThreshold = 0.8 } = {}) => {
+    const total = toMs(start, process.hrtime.bigint())
+
+    const flat = flatten(events)
+      .map((e) => ({
+        ...e,
+        ratio: e.duration / total,
+        hot: e.duration / total >= hotThreshold
+      }))
+      .sort((a, b) => b.duration - a.duration)
+      .slice(0, top)
+
+    return { total, top: flat }
+  }
+
+  return { step, measure, end, summary }
+}

package/src/utils/trace.mjs

@@ -0,0 +1,40 @@
+import fs from 'fs'
+
+export const exportChromeTrace = (events, file) => {
+  const traceEvents = []
+  const pid = 1
+  const tid = 1
+
+  const walk = (nodes) => {
+    for (const n of nodes) {
+      traceEvents.push({
+        name: n.name,
+        cat: 'wukong',
+        ph: 'X', // complete event
+        ts: Math.round(n.start * 1000), // ms → μs
+        dur: Math.round(n.duration * 1000),
+        pid,
+        tid,
+        args: {
+          duration_ms: n.duration,
+          depth: n.depth,
+          ...(n.source && {
+            source: n.source.original
+              ? `${n.source.original.source}:${n.source.original.line}`
+              : `${n.source.file}:${n.source.line}`
+          })
+        }
+      })
+
+      if (n.children?.length) walk(n.children)
+    }
+  }
+
+  walk(events)
+
+  fs.writeFileSync(
+    file,
+    JSON.stringify({ traceEvents }, null, 2),
+    'utf8'
+  )
+}