dsh-git-push 2.20.19 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -2
- package/cli-tool.mjs +2 -4
- package/cli.mjs +7 -1
- package/lib/app/apply.js +4 -4
- package/lib/app/command-registry.js +22 -17
- package/lib/app/handlers/meta.js +2 -2
- package/lib/app/handlers/preprocess.js +107 -0
- package/lib/app/handlers/repo-actions.js +2 -2
- package/lib/app/http-handlers.js +13 -42
- package/lib/app/index.js +2 -1
- package/lib/app/inject-text.js +3 -3
- package/lib/app/preprocess-client.js +136 -0
- package/lib/app/repo-ownership.js +1 -1
- package/lib/app/schema.js +3 -3
- package/lib/app/severity.js +14 -0
- package/lib/app/slash-commands.js +5 -164
- package/lib/app/tool-call.js +73 -144
- package/lib/cli/commands-preprocess.mjs +74 -0
- package/lib/cli/commands-tool.mjs +3 -2
- package/lib/cli/commands-vcs.mjs +4 -4
- package/lib/cli/shared.mjs +35 -9
- package/lib/commit-push/pre-commit-engine.js +57 -10
- package/lib/commit-push.js +71 -27
- package/lib/{exempt/index.js → git/exempt-markers.js} +8 -1
- package/lib/git/ignore.js +1 -1
- package/lib/git/repos.js +2 -2
- package/lib/git/sensitive.js +1 -1
- package/lib/npm/publish.js +20 -5
- package/lib/plugin/auto-push.js +2 -2
- package/lib/preprocess/providers.js +191 -0
- package/lib/self/index.js +1 -1
- package/lib/skip-dirs.js +14 -55
- package/package.json +29 -37
- package/scripts/build-client.mjs +2 -0
- package/scripts/check.mjs +4 -2
- package/scripts/local-registry.mjs +2 -1
- package/cli-audit.mjs +0 -141
- package/lib/app/audit-api.js +0 -173
- package/lib/app/handlers/audit.js +0 -150
- package/lib/app/host-doc-checks.js +0 -25
- package/lib/app/scope-check.js +0 -69
- package/lib/ast/brace.js +0 -120
- package/lib/ast/callgraph.js +0 -135
- package/lib/ast/code-lines.js +0 -175
- package/lib/ast/consts.js +0 -12
- package/lib/ast/control-flow.js +0 -470
- package/lib/ast/credential.js +0 -315
- package/lib/ast/dataflow.js +0 -391
- package/lib/ast/dup-code.js +0 -165
- package/lib/ast/fs-hotspots.js +0 -154
- package/lib/ast/index.js +0 -38
- package/lib/ast/io-risk-const.js +0 -95
- package/lib/ast/io-risk-fn.js +0 -208
- package/lib/ast/io-risk-loop.js +0 -308
- package/lib/ast/io-risk.js +0 -314
- package/lib/ast/lang.js +0 -156
- package/lib/ast/line-count.js +0 -52
- package/lib/ast/magic-number.js +0 -272
- package/lib/ast/naming.js +0 -292
- package/lib/ast/perf.js +0 -488
- package/lib/ast/scope-collisions.js +0 -228
- package/lib/ast/scope.js +0 -241
- package/lib/ast/shell.js +0 -131
- package/lib/ast/size.js +0 -448
- package/lib/ast/symbol-index.js +0 -399
- package/lib/ast/tokenizer.js +0 -421
- package/lib/ast/treesitter.js +0 -413
- package/lib/audit/analysis-coverage.js +0 -98
- package/lib/audit/audit-file.js +0 -205
- package/lib/audit/auditignore-rules.js +0 -148
- package/lib/audit/checks.js +0 -17
- package/lib/audit/client-entry.js +0 -93
- package/lib/audit/collector.js +0 -610
- package/lib/audit/ext-runner.js +0 -80
- package/lib/audit/file-context.js +0 -391
- package/lib/audit/finding.js +0 -101
- package/lib/audit/gitignore-match.js +0 -113
- package/lib/audit/glob.js +0 -63
- package/lib/audit/history-report.js +0 -100
- package/lib/audit/history.js +0 -126
- package/lib/audit/ignore-blind.js +0 -102
- package/lib/audit/index.js +0 -33
- package/lib/audit/orchestrate.js +0 -672
- package/lib/audit/public.js +0 -24
- package/lib/audit/repo-level.js +0 -30
- package/lib/audit/report-yaml.js +0 -90
- package/lib/audit/scope-policy.js +0 -110
- package/lib/audit/slot.js +0 -66
- package/lib/audit-rules/audit-rules-comment.yml +0 -199
- package/lib/audit-rules/audit-rules-cpp.yml +0 -114
- package/lib/audit-rules/audit-rules-csharp.yml +0 -82
- package/lib/audit-rules/audit-rules-docs.yml +0 -32
- package/lib/audit-rules/audit-rules-dsh.yml +0 -177
- package/lib/audit-rules/audit-rules-filehealth.yml +0 -42
- package/lib/audit-rules/audit-rules-folder.yml +0 -99
- package/lib/audit-rules/audit-rules-frontend.yml +0 -335
- package/lib/audit-rules/audit-rules-go.yml +0 -103
- package/lib/audit-rules/audit-rules-i18n.yml +0 -45
- package/lib/audit-rules/audit-rules-java.yml +0 -105
- package/lib/audit-rules/audit-rules-nodejs.yml +0 -662
- package/lib/audit-rules/audit-rules-npm.yml +0 -187
- package/lib/audit-rules/audit-rules-paths.yml +0 -98
- package/lib/audit-rules/audit-rules-performance.yml +0 -245
- package/lib/audit-rules/audit-rules-php.yml +0 -101
- package/lib/audit-rules/audit-rules-private.yml +0 -24
- package/lib/audit-rules/audit-rules-python.yml +0 -106
- package/lib/audit-rules/audit-rules-robustness.yml +0 -31
- package/lib/audit-rules/audit-rules-rust.yml +0 -109
- package/lib/audit-rules/audit-rules-structure.yml +0 -158
- package/lib/audit-rules/audit-rules-swift.yml +0 -99
- package/lib/audit-rules/audit-rules-template.yml +0 -108
- package/lib/audit-ui-sdk/contract.js +0 -117
- package/lib/audit-ui-sdk/index.js +0 -17
- package/lib/checks/button-bind.js +0 -347
- package/lib/checks/common.js +0 -170
- package/lib/checks/credential-file.js +0 -43
- package/lib/checks/dataflow.js +0 -40
- package/lib/checks/dispatch.js +0 -117
- package/lib/checks/dup-code.js +0 -69
- package/lib/checks/dup-const.js +0 -232
- package/lib/checks/file-health.js +0 -150
- package/lib/checks/filter.js +0 -137
- package/lib/checks/folder.js +0 -173
- package/lib/checks/fs-scanner.js +0 -57
- package/lib/checks/hardcoded-path.js +0 -98
- package/lib/checks/index.js +0 -49
- package/lib/checks/io.js +0 -66
- package/lib/checks/magic-number.js +0 -42
- package/lib/checks/npm-json.js +0 -273
- package/lib/checks/private.js +0 -64
- package/lib/checks/regex.js +0 -298
- package/lib/checks/scope-collision.js +0 -68
- package/lib/checks/semantic.js +0 -134
- package/lib/checks/structural.js +0 -281
- package/lib/cli/commands-audit.mjs +0 -142
- package/lib/cli/commands-doc.mjs +0 -127
- package/lib/client-parts/audit/audit.js +0 -301
- package/lib/exempt/tool.js +0 -198
- package/lib/git/module-splitter.js +0 -47
- package/lib/link-check/index.js +0 -187
- package/lib/lint-adapter/detect.js +0 -161
- package/lib/lint-adapter/index.js +0 -50
- package/lib/lint-adapter/runner.js +0 -133
- package/lib/preprocess/audit.js +0 -98
- package/lib/preprocess/index.js +0 -78
- package/lib/rule/compilers/credential.js +0 -62
- package/lib/rule/compilers/dataflow.js +0 -38
- package/lib/rule/compilers/file-health.js +0 -75
- package/lib/rule/compilers/frontend.js +0 -86
- package/lib/rule/compilers/func.js +0 -35
- package/lib/rule/compilers/helpers.js +0 -71
- package/lib/rule/compilers/index.js +0 -29
- package/lib/rule/compilers/link-semantic.js +0 -45
- package/lib/rule/compilers/list-kinds.js +0 -12
- package/lib/rule/compilers/numeric-kinds.js +0 -73
- package/lib/rule/compilers/regex.js +0 -78
- package/lib/rule/compilers/structure.js +0 -107
- package/lib/rule/compilers.js +0 -17
- package/lib/rule/homoglyph.js +0 -45
- package/lib/rule/loader.js +0 -274
- package/lib/rule/registry.js +0 -122
- package/lib/rule/scope.js +0 -67
- package/lib/score/docs-score.js +0 -166
- package/lib/score/index.js +0 -234
- package/scripts/__pycache__/module-splitter.cpython-38.pyc +0 -0
- package/scripts/audit-ext/_example-readme-present.mjs +0 -34
- package/scripts/audit-ext/dsh-inject-declarations.mjs +0 -209
- package/scripts/audit-ext/variable-min-length.mjs +0 -102
- package/scripts/audit-gate.mjs +0 -235
- package/scripts/audit-runner.mjs +0 -35
- package/scripts/audit-runtime-check.mjs +0 -129
- package/scripts/browser-page-probe.mjs +0 -271
- package/scripts/check-js-scope.mjs +0 -87
- package/scripts/clean-date-comments.py +0 -102
- package/scripts/cpu-sample.mjs +0 -188
- package/scripts/doc-drift.mjs +0 -200
- package/scripts/hot-path-probe-cjs.cjs +0 -71
- package/scripts/hot-path-probe-fs-shim.mjs +0 -28
- package/scripts/hot-path-probe-fsp-shim.mjs +0 -31
- package/scripts/hot-path-probe.mjs +0 -153
- package/scripts/module-splitter.py +0 -800
- package/scripts/picker-repro.mjs +0 -115
- package/scripts/platform-scan.mjs +0 -168
- package/scripts/probe-recheck.mjs +0 -47
- package/scripts/rename-locator.mjs +0 -97
- package/scripts/rule-switch.mjs +0 -97
- package/scripts/rules-solo-audit.mjs +0 -173
- package/scripts/scan-file-io.mjs +0 -717
- package/scripts/scan-fs-hotspots.mjs +0 -107
- package/scripts/symbol-index.mjs +0 -85
- package/scripts/verify-prestep.mjs +0 -100
- package/skills/dev/audit-rule-authoring.md +0 -58
- package/skills/guide/guide-audit.md +0 -270
- /package/lib/{audit → app}/ownership.js +0 -0
- /package/lib/app/{schema-audit.js → schema-preprocess.js} +0 -0
- /package/lib/{audit-defaults.js → git/defaults.js} +0 -0
package/scripts/cpu-sample.mjs
DELETED
|
@@ -1,188 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* CPU 现场采样器(独立脚本,按需启动;零依赖、只读 /proc)。
|
|
4
|
-
*
|
|
5
|
-
* 用途:CPU 异常(如经常 50%+)时**现场**抓证据——事后采样复现不出来,
|
|
6
|
-
* 必须在「异常正在发生」的那一刻记录:哪个进程、什么命令行、系统总占用、
|
|
7
|
-
* 是否 chrome/headless 在跑、宿主进程内存等。
|
|
8
|
-
*
|
|
9
|
-
* 为什么不做成插件常驻任务:30s 常驻采样虽便宜,但平时没人看,反而多一份常驻逻辑;
|
|
10
|
-
* 按需启动最省事,也不给宿主添负担。
|
|
11
|
-
*
|
|
12
|
-
* 用法:
|
|
13
|
-
* node scripts/cpu-sample.mjs # 默认 120 秒、每 5 秒一次
|
|
14
|
-
* node scripts/cpu-sample.mjs --seconds 300 --interval 2 --top 8
|
|
15
|
-
* node scripts/cpu-sample.mjs --out /tmp/cpu.jsonl --high 40
|
|
16
|
-
*
|
|
17
|
-
* 输出:① 控制台一行一样本(系统% + Top 进程)② JSONL 明细(每样本一行,含命令行)
|
|
18
|
-
* ③ 结束打印汇总(峰值、Top 常客、chrome 出现次数)与 JSONL 路径。
|
|
19
|
-
*
|
|
20
|
-
* 判定口径:进程 CPU% = 该进程 tick 增量 / 全机 tick 增量 × 100(= 占整机百分比,
|
|
21
|
-
* 与 top 的聚合口径一致);系统% = 1 - idle 增量/总增量。
|
|
22
|
-
*/
|
|
23
|
-
import { readdirSync, readFileSync, appendFileSync, existsSync } from 'node:fs';
|
|
24
|
-
import { cpus, loadavg, hostname } from 'node:os';
|
|
25
|
-
import { join } from 'node:path';
|
|
26
|
-
|
|
27
|
-
const argv = process.argv.slice(2);
|
|
28
|
-
const arg = (name, dflt) => {
|
|
29
|
-
const i = argv.indexOf(`--${name}`);
|
|
30
|
-
return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : dflt;
|
|
31
|
-
};
|
|
32
|
-
const SECONDS = Math.max(5, Number(arg('seconds', 120)) || 120);
|
|
33
|
-
const INTERVAL = Math.max(1, Number(arg('interval', 5)) || 5);
|
|
34
|
-
const TOP = Math.max(3, Number(arg('top', 6)) || 6);
|
|
35
|
-
const HIGH = Number(arg('high', 40)) || 40;
|
|
36
|
-
const OUT = String(arg('out', '') || '') || `/tmp/cpu-sample-${new Date().toISOString().replace(/[:.]/g, '-')}.jsonl`;
|
|
37
|
-
const NCPU = cpus().length || 1;
|
|
38
|
-
|
|
39
|
-
/** 读 /proc/stat 的 cpu 汇总行 → { total, idle }(单位:tick)。 */
|
|
40
|
-
function cpuTotals() {
|
|
41
|
-
try {
|
|
42
|
-
const line = readFileSync('/proc/stat', 'utf8').split('\n')[0] || '';
|
|
43
|
-
const f = line.trim().split(/\s+/).slice(1).map(Number);
|
|
44
|
-
const total = f.reduce((a, b) => a + (Number.isFinite(b) ? b : 0), 0);
|
|
45
|
-
const idle = (f[3] || 0) + (f[4] || 0); // idle + iowait
|
|
46
|
-
return { total, idle };
|
|
47
|
-
} catch { return { total: 0, idle: 0 }; }
|
|
48
|
-
}
|
|
49
|
-
|
|
50
|
-
/** 读某进程累计 CPU tick(utime+stime)。comm 可能含空格/括号 ⇒ 取最后一个 ')' 之后解析。 */
|
|
51
|
-
function procTicks(pid) {
|
|
52
|
-
try {
|
|
53
|
-
const s = readFileSync(`/proc/${pid}/stat`, 'utf8');
|
|
54
|
-
const rest = s.slice(s.lastIndexOf(')') + 2).trim().split(/\s+/);
|
|
55
|
-
// rest[0] = state ⇒ utime 是第 12 个字段(1-based 14)⇒ rest 下标 11、12
|
|
56
|
-
return (Number(rest[11]) || 0) + (Number(rest[12]) || 0);
|
|
57
|
-
} catch { return null; }
|
|
58
|
-
}
|
|
59
|
-
|
|
60
|
-
/** 某进程常驻内存 MB(statm 第 2 项 = resident pages)。 */
|
|
61
|
-
function procRssMB(pid) {
|
|
62
|
-
try {
|
|
63
|
-
const f = readFileSync(`/proc/${pid}/statm`, 'utf8').trim().split(/\s+/);
|
|
64
|
-
return Math.round(((Number(f[1]) || 0) * 4096) / 1048576);
|
|
65
|
-
} catch { return 0; }
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
/** 进程名与命令行(cmdline 为 NUL 分隔;截断到 160 字符)。 */
|
|
69
|
-
function procInfo(pid) {
|
|
70
|
-
let comm = '';
|
|
71
|
-
let cmd = '';
|
|
72
|
-
try { comm = readFileSync(`/proc/${pid}/comm`, 'utf8').trim(); } catch { /* 进程可能已退出 */ }
|
|
73
|
-
try { cmd = readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean).join(' '); } catch { /* 同上 */ }
|
|
74
|
-
return { comm, cmd: cmd.slice(0, 160) };
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
/** 枚举 /proc 下的数字目录(= 进程)。 */
|
|
78
|
-
function pids() {
|
|
79
|
-
try { return readdirSync('/proc').filter((n) => /^\d+$/.test(n)); } catch { return []; }
|
|
80
|
-
}
|
|
81
|
-
|
|
82
|
-
/** 内存概况(MB)。 */
|
|
83
|
-
function memMB() {
|
|
84
|
-
try {
|
|
85
|
-
const t = readFileSync('/proc/meminfo', 'utf8');
|
|
86
|
-
const get = (k) => Number((t.match(new RegExp(`^${k}:\\s+(\\d+) kB`, 'm')) || [])[1] || 0) / 1024;
|
|
87
|
-
return { total: Math.round(get('MemTotal')), available: Math.round(get('MemAvailable')) };
|
|
88
|
-
} catch { return { total: 0, available: 0 }; }
|
|
89
|
-
}
|
|
90
|
-
|
|
91
|
-
let prev = null; // { t: {total,idle}, pids: Map<pid, ticks> }
|
|
92
|
-
let hostPid = null;
|
|
93
|
-
const samples = [];
|
|
94
|
-
|
|
95
|
-
function detectHostPid() {
|
|
96
|
-
for (const p of pids()) {
|
|
97
|
-
const { cmd } = procInfo(p);
|
|
98
|
-
if (cmd.includes('packages/DeepSeekHarness-NAS/target/bin/node')) return Number(p);
|
|
99
|
-
}
|
|
100
|
-
return null;
|
|
101
|
-
}
|
|
102
|
-
|
|
103
|
-
/** 采一次样并返回记录(纯读,不抛错)。 */
|
|
104
|
-
function sampleOnce() {
|
|
105
|
-
const now = cpuTotals();
|
|
106
|
-
const cur = new Map();
|
|
107
|
-
for (const p of pids()) {
|
|
108
|
-
const t = procTicks(p);
|
|
109
|
-
if (t !== null) cur.set(p, t);
|
|
110
|
-
}
|
|
111
|
-
const rec = {
|
|
112
|
-
t: new Date().toISOString(),
|
|
113
|
-
ncpu: NCPU,
|
|
114
|
-
systemPct: null,
|
|
115
|
-
load: loadavg().map((x) => Number(x.toFixed(2))),
|
|
116
|
-
mem: memMB(),
|
|
117
|
-
host: null,
|
|
118
|
-
chrome: 0,
|
|
119
|
-
browsersvc: 0,
|
|
120
|
-
top: [],
|
|
121
|
-
};
|
|
122
|
-
if (prev && now.total > prev.t.total) {
|
|
123
|
-
const dTot = now.total - prev.t.total;
|
|
124
|
-
const dIdle = now.idle - prev.t.idle;
|
|
125
|
-
rec.systemPct = Number((100 * (1 - dIdle / dTot)).toFixed(1));
|
|
126
|
-
const list = [];
|
|
127
|
-
for (const [pid, ticks] of cur) {
|
|
128
|
-
const old = prev.pids.get(pid);
|
|
129
|
-
if (old === undefined) continue; // 新进程首个样本跳过(无基线)
|
|
130
|
-
const d = ticks - old;
|
|
131
|
-
if (d <= 0) continue;
|
|
132
|
-
const pct = Number(((100 * d) / dTot).toFixed(1));
|
|
133
|
-
if (pct < 0.2) continue;
|
|
134
|
-
const info = procInfo(pid);
|
|
135
|
-
list.push({ pid: Number(pid), pct, rssMB: procRssMB(pid), ...info });
|
|
136
|
-
}
|
|
137
|
-
list.sort((a, b) => b.pct - a.pct);
|
|
138
|
-
rec.top = list.slice(0, TOP);
|
|
139
|
-
rec.chrome = list.filter((x) => /chrome|headless/i.test(x.comm)).length;
|
|
140
|
-
rec.browsersvc = list.filter((x) => /browsersvc/i.test(x.cmd) && !/cpu-sample/.test(x.cmd)).length;
|
|
141
|
-
if (hostPid === null) hostPid = detectHostPid();
|
|
142
|
-
const h = hostPid ? list.find((x) => x.pid === hostPid) : null;
|
|
143
|
-
rec.host = h ? { pid: h.pid, pct: h.pct, rssMB: h.rssMB } : (hostPid ? { pid: hostPid, pct: 0, rssMB: procRssMB(hostPid) } : null);
|
|
144
|
-
}
|
|
145
|
-
prev = { t: now, pids: cur };
|
|
146
|
-
return rec;
|
|
147
|
-
}
|
|
148
|
-
|
|
149
|
-
function line(rec) {
|
|
150
|
-
const hi = rec.systemPct !== null && rec.systemPct >= HIGH;
|
|
151
|
-
const head = `${rec.t.slice(11, 19)} 系统 ${rec.systemPct === null ? '--' : `${rec.systemPct}%`} load ${rec.load[0]} mem ${rec.mem.available}/${rec.mem.total}MB chrome ${rec.chrome} browsersvc ${rec.browsersvc}`;
|
|
152
|
-
const tops = rec.top.slice(0, 4).map((x) => `${x.comm}:${x.pct}%`).join(' ');
|
|
153
|
-
return `${hi ? '⚠️ 高占用 ' : ' '}${head}${tops ? ` | ${tops}` : ''}`;
|
|
154
|
-
}
|
|
155
|
-
|
|
156
|
-
// ── 主流程 ──
|
|
157
|
-
console.log(`CPU 现场采样器 · 主机 ${hostname()} · ${NCPU} 核 · 每 ${INTERVAL}s 一次 · 共 ${SECONDS}s · 高占用阈值 ${HIGH}%`);
|
|
158
|
-
console.log(`输出 JSONL:${OUT}`);
|
|
159
|
-
sampleOnce(); // 建立基线(首样本无百分比)
|
|
160
|
-
let n = 0;
|
|
161
|
-
const timer = setInterval(() => {
|
|
162
|
-
const rec = sampleOnce();
|
|
163
|
-
n += 1;
|
|
164
|
-
samples.push(rec);
|
|
165
|
-
console.log(line(rec));
|
|
166
|
-
try { appendFileSync(OUT, `${JSON.stringify(rec)}\n`); } catch { /* 写失败不影响采样 */ }
|
|
167
|
-
if (n * INTERVAL >= SECONDS) finish();
|
|
168
|
-
}, INTERVAL * 1000);
|
|
169
|
-
|
|
170
|
-
function finish() {
|
|
171
|
-
clearInterval(timer);
|
|
172
|
-
const withPct = samples.filter((s) => s.systemPct !== null);
|
|
173
|
-
const peak = withPct.reduce((m, s) => Math.max(m, s.systemPct), 0);
|
|
174
|
-
const counter = new Map();
|
|
175
|
-
for (const s of withPct) for (const x of s.top) counter.set(x.comm, (counter.get(x.comm) || 0) + x.pct);
|
|
176
|
-
const regulars = [...counter.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6)
|
|
177
|
-
.map(([c, v]) => `${c}(${Math.round(v)}%)`);
|
|
178
|
-
const chromeHits = withPct.filter((s) => s.chrome > 0).length;
|
|
179
|
-
console.log('\n── 汇总 ──');
|
|
180
|
-
console.log(`样本数 ${withPct.length} · 系统峰值 ${peak}% · 平均 ${withPct.length ? (withPct.reduce((a, s) => a + s.systemPct, 0) / withPct.length).toFixed(1) : 0}%`);
|
|
181
|
-
console.log(`chrome/headless 出现样本数:${chromeHits}/${withPct.length}`);
|
|
182
|
-
console.log(`Top 常客(按累计 %):${regulars.join(' · ') || '(无)'}`);
|
|
183
|
-
console.log(`明细:${OUT}`);
|
|
184
|
-
process.exit(0);
|
|
185
|
-
}
|
|
186
|
-
|
|
187
|
-
// Ctrl-C 也能出汇总
|
|
188
|
-
process.on('SIGINT', finish);
|
package/scripts/doc-drift.mjs
DELETED
|
@@ -1,200 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
// dsh-skip-i18n: CLI 输出硬编码中文为产品行为(无 i18n 需求)
|
|
3
|
-
/**
|
|
4
|
-
* doc-drift.mjs — 文档计数与代码实际值的一致性校验(只读,不写盘)
|
|
5
|
-
*
|
|
6
|
-
* 为什么需要它(2026-10-11 实测):同一事实在多处手写必然分叉——
|
|
7
|
-
* · README 写「14 个规则包 / 14 个规则槽位」,实际 `lib/audit-rules/` 有 21 个 yml;
|
|
8
|
-
* · `docs/功能-审计规则体系.md` 写「124 条规则」、`docs/SPEC.md` 写「122 条规则」,
|
|
9
|
-
* 而实际规则条数是 125(`^ - id:` 两空格缩进的规则行)。
|
|
10
|
-
* 三份文档三个数字,改一处不会带动其它处 ⇒ 本脚本把它变成"提交前机器能拦"。
|
|
11
|
-
*
|
|
12
|
-
* 计数口径(单一事实源):
|
|
13
|
-
* · 槽位数 = `lib/audit-rules/*.yml` 文件数(目录即清单,放文件即生效);
|
|
14
|
-
* · 规则条数 = 所有 yml 里 `^ - id:` 行数(rules 列表下两空格缩进的正规规则行)。
|
|
15
|
-
*
|
|
16
|
-
* 用法:
|
|
17
|
-
* node scripts/doc-drift.mjs # 校验(不一致 exit 1)
|
|
18
|
-
* node scripts/doc-drift.mjs --json # 机器可读
|
|
19
|
-
* node scripts/doc-drift.mjs --quiet # 只输出结论
|
|
20
|
-
*/
|
|
21
|
-
import { readdirSync, readFileSync, existsSync } from 'node:fs';
|
|
22
|
-
import { join, dirname, relative } from 'node:path';
|
|
23
|
-
import { fileURLToPath } from 'node:url';
|
|
24
|
-
|
|
25
|
-
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
26
|
-
const ROOT = join(__dirname, '..');
|
|
27
|
-
const argv = process.argv.slice(2);
|
|
28
|
-
const asJson = argv.includes('--json');
|
|
29
|
-
const quiet = argv.includes('--quiet');
|
|
30
|
-
|
|
31
|
-
/** 统计槽位(yml 文件)与规则条数(`^ - id:`)。 */
|
|
32
|
-
export function countRules(root = ROOT) {
|
|
33
|
-
const dir = join(root, 'lib', 'audit-rules');
|
|
34
|
-
if (!existsSync(dir)) return { slots: 0, rules: 0, files: [] };
|
|
35
|
-
const files = readdirSync(dir).filter((f) => f.endsWith('.yml')).sort();
|
|
36
|
-
let rules = 0;
|
|
37
|
-
for (const f of files) {
|
|
38
|
-
const text = readFileSync(join(dir, f), 'utf8');
|
|
39
|
-
rules += (text.match(/^ {2}- id:/gm) || []).length;
|
|
40
|
-
}
|
|
41
|
-
return { slots: files.length, rules, files };
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
/** 待校验的文档(存在才查)。 */
|
|
45
|
-
function docFiles(root = ROOT) {
|
|
46
|
-
const cands = [
|
|
47
|
-
join(root, 'README.md'),
|
|
48
|
-
join(root, 'docs', 'SPEC.md'),
|
|
49
|
-
join(root, 'docs', '功能-审计规则体系.md'),
|
|
50
|
-
join(root, 'docs', 'FUNCTIONS.md'),
|
|
51
|
-
];
|
|
52
|
-
return cands.filter((p) => existsSync(p));
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
/**
|
|
56
|
-
* 设置键数(真实口径):`settings-set` 的白名单 `allowedKeys = new Set([...])`
|
|
57
|
-
* ——它就是「前端可写的设置键」权威清单(README/SPEC 说的 18 个即此)。
|
|
58
|
-
* 取不到返回 null,调用方跳过该项(不误报)。
|
|
59
|
-
*/
|
|
60
|
-
export function countSettings(root = ROOT) {
|
|
61
|
-
try {
|
|
62
|
-
const p = join(root, 'lib', 'app', 'handlers', 'settings.js');
|
|
63
|
-
const text = readFileSync(p, 'utf8');
|
|
64
|
-
const m = /allowedKeys\s*=\s*new Set\(\[([\s\S]*?)\]\)/.exec(text);
|
|
65
|
-
if (!m) return null;
|
|
66
|
-
return (m[1].match(/'[A-Za-z][A-Za-z0-9]*'/g) || []).length;
|
|
67
|
-
} catch {
|
|
68
|
-
return null;
|
|
69
|
-
}
|
|
70
|
-
}
|
|
71
|
-
|
|
72
|
-
/**
|
|
73
|
-
* HTTP 接口数(真实口径):`lib/app/http-handlers.js` 里 `case '/api/git-push/…'` 的唯一路径数
|
|
74
|
-
* ——分发器就是路由真相(SPEC 的「28 条」即此)。
|
|
75
|
-
*/
|
|
76
|
-
export function countRoutes(root = ROOT) {
|
|
77
|
-
try {
|
|
78
|
-
const p = join(root, 'lib', 'app', 'http-handlers.js');
|
|
79
|
-
const text = readFileSync(p, 'utf8');
|
|
80
|
-
const set = new Set((text.match(/case '\/api\/git-push\/[A-Za-z0-9/_-]+'/g) || []));
|
|
81
|
-
return set.size || null;
|
|
82
|
-
} catch {
|
|
83
|
-
return null;
|
|
84
|
-
}
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
/**
|
|
88
|
-
* 扫描文档里手写的计数并比对实际值。
|
|
89
|
-
* 覆盖**全部出现处**(README 里"14 个规则包"曾出现在多行,只查第一处会漏)。
|
|
90
|
-
* @returns {Array<{file:string,line:number,text:string,kind:string,doc:number,actual:number}>}
|
|
91
|
-
*/
|
|
92
|
-
export function findCountDrift(root = ROOT, actual = countRules(root), toolCount = null) {
|
|
93
|
-
const issues = [];
|
|
94
|
-
// ①「N 个规则包 / N 个规则槽位 / N 个槽位」→ 比槽位数
|
|
95
|
-
const slotRe = /(\d+)\s*个(?:规则)?(?:包|槽位)/g;
|
|
96
|
-
// ②「N 条规则」→ 比规则条数
|
|
97
|
-
const ruleRe = /(\d+)\s*条规则/g;
|
|
98
|
-
// ③「N 个工具」→ 比 listTools() 条数(**用真实 API 取口径**,不用正则数代码)
|
|
99
|
-
// 两种语序都要认:`17 个工具` 与 `工具(17 个…)`——此前只认前者,漏掉了 SPEC 的「工具(14 个)」(实测盲区)。
|
|
100
|
-
const toolRe = /(\d+)\s*个工具|工具\s*[((]\s*(\d+)\s*个/g;
|
|
101
|
-
// ④「N 个设置键」→ 比 settings-set 白名单条数
|
|
102
|
-
const setRe = /(\d+)\s*个设置键/g;
|
|
103
|
-
// ⑤「N 条 HTTP 接口 / N 条 HTTP API / HTTP 接口(N 条…)/ HTTP API(N 条…)」→ 比分发器 case 唯一路径数
|
|
104
|
-
// 为什么四个语序都要认:此前只认「N 条 HTTP 接口」,漏掉了 docs/SPEC.md 工具表里的「N 条 HTTP API」
|
|
105
|
-
// 与接口章标题「HTTP 接口(N 条,前缀…)」——实测盲区(文档写 28、实际 34 却不报)。
|
|
106
|
-
const routeRe = /(\d+)\s*条\s*HTTP\s*(?:接口|API)|HTTP\s*(?:接口|API)\s*[((]\s*(\d+)\s*条/g;
|
|
107
|
-
const tools = toolCount;
|
|
108
|
-
const settings = countSettings(root);
|
|
109
|
-
const routes = countRoutes(root);
|
|
110
|
-
for (const file of docFiles(root)) {
|
|
111
|
-
const lines = readFileSync(file, 'utf8').split('\n');
|
|
112
|
-
lines.forEach((text, i) => {
|
|
113
|
-
const pairs = [[slotRe, '槽位数', actual.slots], [ruleRe, '规则条数', actual.rules]];
|
|
114
|
-
if (tools !== null) pairs.push([toolRe, '工具数', tools]);
|
|
115
|
-
if (settings !== null) pairs.push([setRe, '设置键数', settings]);
|
|
116
|
-
if (routes !== null) pairs.push([routeRe, 'HTTP 接口数', routes]);
|
|
117
|
-
for (const [re, kind, want] of pairs) {
|
|
118
|
-
re.lastIndex = 0;
|
|
119
|
-
let m;
|
|
120
|
-
while ((m = re.exec(text))) {
|
|
121
|
-
const doc = Number(m[1] ?? m[2]);
|
|
122
|
-
if (doc !== want) {
|
|
123
|
-
issues.push({ file: relative(root, file), line: i + 1, text: m[0], kind, doc, actual: want });
|
|
124
|
-
}
|
|
125
|
-
}
|
|
126
|
-
}
|
|
127
|
-
});
|
|
128
|
-
}
|
|
129
|
-
return issues;
|
|
130
|
-
}
|
|
131
|
-
|
|
132
|
-
/**
|
|
133
|
-
* 工具清单完整性:每个已注册工具名都必须在 `docs/SPEC.md` 出现(反引号形式)。
|
|
134
|
-
* 为什么需要:**计数一致 ≠ 清单完整**——实测出现过「计数改对了,但漏列一个新工具的行」(npm_publish)。
|
|
135
|
-
* @returns {Array<{file:string, name:string}>}
|
|
136
|
-
*/
|
|
137
|
-
export function findToolListGaps(root = ROOT, toolNames = []) {
|
|
138
|
-
const out = [];
|
|
139
|
-
if (!Array.isArray(toolNames) || !toolNames.length) return out;
|
|
140
|
-
const spec = join(root, 'docs', 'SPEC.md');
|
|
141
|
-
if (!existsSync(spec)) return out;
|
|
142
|
-
const text = readFileSync(spec, 'utf8');
|
|
143
|
-
for (const n of toolNames) if (!text.includes('`' + n + '`')) out.push({ file: 'docs/SPEC.md', name: n });
|
|
144
|
-
return out;
|
|
145
|
-
}
|
|
146
|
-
|
|
147
|
-
/** 已注册工具名清单(与 countToolsAsync 同源;取不到返回空数组,不误报)。 */
|
|
148
|
-
export async function toolNamesAsync(root = ROOT) {
|
|
149
|
-
try {
|
|
150
|
-
const mod = await import('file://' + join(root, 'lib', 'app', 'tools.js'));
|
|
151
|
-
const list = typeof mod.listTools === 'function' ? mod.listTools() : null;
|
|
152
|
-
return Array.isArray(list) ? list.map((t) => t.name).filter(Boolean) : [];
|
|
153
|
-
} catch {
|
|
154
|
-
return [];
|
|
155
|
-
}
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
/**
|
|
159
|
-
* 工具数(真实口径):直接调用插件自己的 `listTools()`——它是宿主注册表的唯一出口,
|
|
160
|
-
* 比用正则数代码里的 `name:` 可靠(本次实测:正则数不出,API 一调就是 16)。
|
|
161
|
-
* 取不到(环境缺依赖等)返回 null,调用方跳过该项校验(不误报)。
|
|
162
|
-
*/
|
|
163
|
-
export async function countToolsAsync(root = ROOT) {
|
|
164
|
-
try {
|
|
165
|
-
const mod = await import('file://' + join(root, 'lib', 'app', 'tools.js'));
|
|
166
|
-
const list = typeof mod.listTools === 'function' ? mod.listTools() : null;
|
|
167
|
-
return Array.isArray(list) ? list.length : null;
|
|
168
|
-
} catch {
|
|
169
|
-
return null;
|
|
170
|
-
}
|
|
171
|
-
}
|
|
172
|
-
|
|
173
|
-
async function main() {
|
|
174
|
-
const actual = countRules(ROOT);
|
|
175
|
-
const toolCount = await countToolsAsync(ROOT);
|
|
176
|
-
const issues = findCountDrift(ROOT, actual, toolCount);
|
|
177
|
-
const gaps = findToolListGaps(ROOT, await toolNamesAsync(ROOT));
|
|
178
|
-
if (asJson) {
|
|
179
|
-
console.log(JSON.stringify({ ok: issues.length === 0 && gaps.length === 0, actual, issues, toolListGaps: gaps }, null, 2));
|
|
180
|
-
process.exit(issues.length || gaps.length ? 1 : 0);
|
|
181
|
-
}
|
|
182
|
-
if (!quiet) console.log(`实际值:${actual.slots} 个槽位 / ${actual.rules} 条规则(lib/audit-rules/)`);
|
|
183
|
-
if (!issues.length && !gaps.length) {
|
|
184
|
-
console.log('文档计数一致性 ✅');
|
|
185
|
-
process.exit(0);
|
|
186
|
-
}
|
|
187
|
-
if (gaps.length) {
|
|
188
|
-
console.error('工具清单不完整 ❌(docs/SPEC.md 工具表缺少以下工具行):');
|
|
189
|
-
for (const g of gaps) console.error(` ${g.file} 缺工具:${g.name}`);
|
|
190
|
-
}
|
|
191
|
-
if (issues.length) {
|
|
192
|
-
console.error('文档计数与代码不一致 ❌(改代码后请同步这些位置,或改为脚本生成):');
|
|
193
|
-
for (const it of issues) {
|
|
194
|
-
console.error(` ${it.file}:${it.line} 写的「${it.text}」→ 实际 ${it.kind} ${it.actual}`);
|
|
195
|
-
}
|
|
196
|
-
}
|
|
197
|
-
process.exit(1);
|
|
198
|
-
}
|
|
199
|
-
|
|
200
|
-
if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) main();
|
|
@@ -1,71 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* CJS 侧探针通道(配合 scripts/hot-path-probe.mjs 的 ESM loader 钩子;由它 createRequire 载入)。
|
|
3
|
-
*
|
|
4
|
-
* 【为什么需要单独一条通道】Node 对 `format: 'commonjs'` **不采用** loader 钩子返回的源码
|
|
5
|
-
* (实测:同一探针下 ESM 目标计数正常,CJS 目标计数为 0),故 CJS 必须走自己的路:
|
|
6
|
-
* patch `Module._extensions['.js'/'.cjs']`。
|
|
7
|
-
*
|
|
8
|
-
* 【为什么用 _compile 重编译,而不是只包 module.exports】只包 `module.exports` 只能统计
|
|
9
|
-
* 「外部调用」;模块内部自调用(helper 调 helper)统计不到。重编译时在源码**末尾追加**
|
|
10
|
-
* 与 ESM 侧同形的包装,即可同时覆盖两种调用——与 ESM 侧行为对称。
|
|
11
|
-
*
|
|
12
|
-
* 【计数容器】与 ESM 侧共用 `globalThis.__HOT_PATH_PROBE__`(同进程同主线程),
|
|
13
|
-
* 故报告由 ESM 侧的退出钩子统一打印,本文件不重复打印。
|
|
14
|
-
*
|
|
15
|
-
* 【失败兜底】包装失败(源码不可读 / 语法异常等)一律**回退原始加载**并 emitWarning——
|
|
16
|
-
* 探针绝不能让被测程序跑不起来。
|
|
17
|
-
*/
|
|
18
|
-
const Module = require('node:module');
|
|
19
|
-
const fs = require('node:fs');
|
|
20
|
-
const { pathToFileURL } = require('node:url');
|
|
21
|
-
|
|
22
|
-
const cfg = (() => {
|
|
23
|
-
try { return JSON.parse(process.env.HOT_PATH_PROBE || '{}'); } catch { return {}; }
|
|
24
|
-
})();
|
|
25
|
-
const targets = cfg.modules || {};
|
|
26
|
-
|
|
27
|
-
const HEADER = '\nconst __HP = (globalThis.__HOT_PATH_PROBE__ ||= { fn: {}, fs: {} });\n'
|
|
28
|
-
+ 'function __hpRecord(__n, __ms) { const __e = (__HP.fn[__n] ||= { calls: 0, ms: 0 }); __e.calls += 1; __e.ms += __ms; }\n';
|
|
29
|
-
|
|
30
|
-
/**
|
|
31
|
-
* 生成与 ESM 侧同形的包装代码。
|
|
32
|
-
* @param {string[]} names 目标函数名
|
|
33
|
-
* @returns {string} 追加到源码末尾的包装片段
|
|
34
|
-
*/
|
|
35
|
-
function suffixFor(names) {
|
|
36
|
-
return names.map((n) => `
|
|
37
|
-
;(() => {
|
|
38
|
-
const __orig = typeof ${n} === 'function' ? ${n} : (module.exports && module.exports.${n});
|
|
39
|
-
if (typeof __orig !== 'function') return;
|
|
40
|
-
const __wrapped = function (...__a) {
|
|
41
|
-
const __t0 = performance.now();
|
|
42
|
-
try { return __orig.apply(this, __a); }
|
|
43
|
-
finally { __hpRecord(${JSON.stringify(n)}, performance.now() - __t0); }
|
|
44
|
-
};
|
|
45
|
-
try { ${n} = __wrapped; } catch { /* 非可变绑定(const 箭头函数等):只兜 exports */ }
|
|
46
|
-
try {
|
|
47
|
-
if (module.exports && module.exports.${n} === __orig) module.exports.${n} = __wrapped;
|
|
48
|
-
} catch { /* 只读导出(getter/冻结)忽略:内部调用已计数 */ }
|
|
49
|
-
})();`).join('');
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
for (const ext of ['.js', '.cjs']) {
|
|
53
|
-
const orig = Module._extensions[ext];
|
|
54
|
-
if (typeof orig !== 'function') continue;
|
|
55
|
-
Module._extensions[ext] = function patchedExtension(mod, filename) {
|
|
56
|
-
const names = targets[pathToFileURL(filename).href];
|
|
57
|
-
if (!Array.isArray(names) || !names.length) return orig.call(this, mod, filename);
|
|
58
|
-
let src;
|
|
59
|
-
try {
|
|
60
|
-
src = fs.readFileSync(filename, 'utf8');
|
|
61
|
-
} catch {
|
|
62
|
-
return orig.call(this, mod, filename);
|
|
63
|
-
}
|
|
64
|
-
try {
|
|
65
|
-
mod._compile(src + HEADER + suffixFor(names), filename);
|
|
66
|
-
} catch (e) {
|
|
67
|
-
process.emitWarning(`hot-path-probe-cjs: 包装失败,已回退原始加载(${filename}):${e && e.message}`);
|
|
68
|
-
return orig.call(this, mod, filename);
|
|
69
|
-
}
|
|
70
|
-
};
|
|
71
|
-
}
|
|
@@ -1,28 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* node:fs 计数 shim(配合 scripts/hot-path-probe.mjs 的 loader 钩子)。
|
|
3
|
-
*
|
|
4
|
-
* ⚠️ 本文件**只负责 `node:fs`**:`node:fs/promises` 由 hot-path-probe-fsp-shim.mjs 负责。
|
|
5
|
-
* 两者必须分开——两个 builtin 的导出面重叠但不同(如 `access`),
|
|
6
|
-
* 若把两个 `export *` 塞进同一模块会触发 **conflicting star exports** 语法错误
|
|
7
|
-
* (实测:真实审计因此崩掉,本注释即该事故的记录)。
|
|
8
|
-
*
|
|
9
|
-
* 做法:`export *` 透传全部导出(避免漏导出导致运行时报错),
|
|
10
|
-
* 再对需计数的少数函数用显式导出**遮蔽**(ESM 里显式导出优先于 star 导出)。
|
|
11
|
-
*/
|
|
12
|
-
|
|
13
|
-
import * as fs from 'node:fs';
|
|
14
|
-
|
|
15
|
-
const HP = (globalThis.__HOT_PATH_PROBE__ ||= { fn: {}, fs: {} });
|
|
16
|
-
const hit = (name) => { HP.fs[name] = (HP.fs[name] || 0) + 1; };
|
|
17
|
-
/** 包一层:先计数再转发(保留 this 与返回值语义)。 */
|
|
18
|
-
const wrap = (mod, name) => (...a) => { hit(name); return mod[name](...a); };
|
|
19
|
-
|
|
20
|
-
export * from 'node:fs';
|
|
21
|
-
export const existsSync = wrap(fs, 'existsSync');
|
|
22
|
-
export const readFileSync = wrap(fs, 'readFileSync');
|
|
23
|
-
export const statSync = wrap(fs, 'statSync');
|
|
24
|
-
export const lstatSync = wrap(fs, 'lstatSync');
|
|
25
|
-
export const readdirSync = wrap(fs, 'readdirSync');
|
|
26
|
-
export const writeFileSync = wrap(fs, 'writeFileSync');
|
|
27
|
-
export const mkdirSync = wrap(fs, 'mkdirSync');
|
|
28
|
-
export const realpathSync = wrap(fs, 'realpathSync');
|
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* node:fs/promises 计数 shim(与 hot-path-probe-fs-shim.mjs 成对;两者必须分开)。
|
|
3
|
-
*
|
|
4
|
-
* 【为什么不能合成一个】`node:fs` 与 `node:fs/promises` 的导出面**重叠但不同**
|
|
5
|
-
* (如 `access` 在两处都存在)⇒ 若把两个 `export *` 放进同一模块,
|
|
6
|
-
* 会出现 **conflicting star exports** 直接报语法错误(实测:真实审计因此崩掉)。
|
|
7
|
-
*
|
|
8
|
-
* 做法同 fs shim:`export *` 透传全部导出(避免漏导出导致运行时报错),
|
|
9
|
-
* 再对需计数的少数函数用显式导出**遮蔽**。
|
|
10
|
-
*/
|
|
11
|
-
|
|
12
|
-
import * as fsp from 'node:fs/promises';
|
|
13
|
-
|
|
14
|
-
const HP = (globalThis.__HOT_PATH_PROBE__ ||= { fn: {}, fs: {} });
|
|
15
|
-
const hit = (name) => { HP.fs[name] = (HP.fs[name] || 0) + 1; };
|
|
16
|
-
/** 包一层:先计数再转发(保留 this 与返回值语义)。 */
|
|
17
|
-
const wrap = (mod, name) => (...a) => { hit(name); return mod[name](...a); };
|
|
18
|
-
|
|
19
|
-
export * from 'node:fs/promises';
|
|
20
|
-
export const readFile = wrap(fsp, 'readFile');
|
|
21
|
-
export const writeFile = wrap(fsp, 'writeFile');
|
|
22
|
-
export const readdir = wrap(fsp, 'readdir');
|
|
23
|
-
export const stat = wrap(fsp, 'stat');
|
|
24
|
-
export const mkdir = wrap(fsp, 'mkdir');
|
|
25
|
-
export const rename = wrap(fsp, 'rename');
|
|
26
|
-
export const unlink = wrap(fsp, 'unlink');
|
|
27
|
-
export const rm = wrap(fsp, 'rm');
|
|
28
|
-
export const access = wrap(fsp, 'access');
|
|
29
|
-
export const symlink = wrap(fsp, 'symlink');
|
|
30
|
-
export const chmod = wrap(fsp, 'chmod');
|
|
31
|
-
export const rmdir = wrap(fsp, 'rmdir');
|
|
@@ -1,153 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* 热路径探针(C1):统计指定模块里关键函数的**耗时 + 调用次数**,并统计 fs 调用次数。
|
|
3
|
-
*
|
|
4
|
-
* 【为什么用 loader 钩子】ESM 的导出绑定与模块命名空间对象都是**只读**的,
|
|
5
|
-
* `mod.fn = wrapper` 这类 monkey-patch 对 import 方**无效**(只对 CJS 有效)。
|
|
6
|
-
* 想在 ESM 里量函数耗时/调用次数,只能在**模块加载时**改源码——本文件即该钩子。
|
|
7
|
-
* 注入方式:给目标模块源码**追加**包装代码。ESM 里模块**自己的函数声明绑定是可变的**
|
|
8
|
-
* (只有 `import` 进来的绑定只读),故模块内部 `fn = wrapper` 会被 import 方看到 ✓。
|
|
9
|
-
*
|
|
10
|
-
* 【一个文件两种角色】(Node 的 register 允许钩子与注册器同文件,用线程区分)
|
|
11
|
-
* · 主线程:把自己注册为 loader 钩子,并在退出时打印统计;
|
|
12
|
-
* · 钩子线程:导出 resolve/load/initialize,负责改源码与重定向 node:fs。
|
|
13
|
-
*
|
|
14
|
-
* 【用法】
|
|
15
|
-
* node --import ./scripts/hot-path-probe.mjs <目标脚本或 -e 代码>
|
|
16
|
-
* 目标由环境变量 HOT_PATH_PROBE 指定(JSON):
|
|
17
|
-
* {"modules":{"<模块绝对URL>":["fn1","fn2"]},"fs":true}
|
|
18
|
-
* 便捷入口:`node scripts/hot-path-probe.mjs run -- <命令...>`(本文件自己起子进程并透传环境)。
|
|
19
|
-
*
|
|
20
|
-
* 【计数落在哪】被改写的代码跑在**主线程**,故 `globalThis.__HOT_PATH_PROBE__` 可直接读。
|
|
21
|
-
*/
|
|
22
|
-
|
|
23
|
-
import { isMainThread } from 'node:worker_threads';
|
|
24
|
-
import { register } from 'node:module';
|
|
25
|
-
import { createRequire } from 'node:module';
|
|
26
|
-
|
|
27
|
-
/** 统计容器(主线程可读;钩子线程里也初始化一份,互不干扰)。 */
|
|
28
|
-
const HP = (globalThis.__HOT_PATH_PROBE__ ||= { fn: {}, fs: {} });
|
|
29
|
-
|
|
30
|
-
/** 从环境读取配置(钩子线程同样能读 process.env)。 */
|
|
31
|
-
function readCfg() {
|
|
32
|
-
try {
|
|
33
|
-
return JSON.parse(process.env.HOT_PATH_PROBE || '{}');
|
|
34
|
-
} catch {
|
|
35
|
-
return {};
|
|
36
|
-
}
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
// ─────────────────────────── 主线程:注册 + 报告 ───────────────────────────
|
|
40
|
-
if (isMainThread) {
|
|
41
|
-
const cfg = readCfg();
|
|
42
|
-
if (!process.env.HOT_PATH_PROBE_ACTIVE) {
|
|
43
|
-
// 作为 --import 预载时:注册钩子(把配置通过 data 传给钩子线程),并在退出时报告。
|
|
44
|
-
process.env.HOT_PATH_PROBE_ACTIVE = '1';
|
|
45
|
-
register(import.meta.url, { data: cfg });
|
|
46
|
-
// 顺带装上 **CJS 通道**:Node 对 format:'commonjs' 不采用 loader 钩子返回的源码(实测计数为 0),
|
|
47
|
-
// 故 CJS 必须 patch Module._extensions;而该 patch 必须在任何 CJS 模块被加载**之前**完成,
|
|
48
|
-
// `--import` 预载正是最早的时机 ⇒ 一个 --import 即可同时覆盖 ESM 与 CJS。
|
|
49
|
-
try {
|
|
50
|
-
createRequire(import.meta.url)('./hot-path-probe-cjs.cjs');
|
|
51
|
-
} catch (e) {
|
|
52
|
-
process.emitWarning(`hot-path-probe: CJS 通道未装上(${e && e.message})——CJS 目标将不会被计数`);
|
|
53
|
-
}
|
|
54
|
-
process.on('exit', () => report());
|
|
55
|
-
}
|
|
56
|
-
|
|
57
|
-
/**
|
|
58
|
-
* 打印统计:函数按累计耗时降序(耗时 + 次数 + 均值),另列 fs 调用次数。
|
|
59
|
-
* 用途:区分「CPU 重复计算」(某函数耗时高、次数多)与「I/O 等待」(fs 次数高)。
|
|
60
|
-
*/
|
|
61
|
-
function report() {
|
|
62
|
-
const fn = Object.entries(HP.fn || {});
|
|
63
|
-
const fs = Object.entries(HP.fs || {});
|
|
64
|
-
if (!fn.length && !fs.length) return;
|
|
65
|
-
const lines = ['', '── 热路径探针 ──'];
|
|
66
|
-
if (fn.length) {
|
|
67
|
-
lines.push('函数(按累计耗时降序):');
|
|
68
|
-
for (const [name, s] of fn.sort((a, b) => b[1].ms - a[1].ms)) {
|
|
69
|
-
lines.push(` ${name.padEnd(28)} 调用 ${String(s.calls).padStart(7)} 次|累计 ${s.ms.toFixed(1).padStart(9)} ms|均值 ${(s.ms / s.calls).toFixed(3)} ms`);
|
|
70
|
-
}
|
|
71
|
-
}
|
|
72
|
-
if (fs.length) {
|
|
73
|
-
lines.push('fs 调用(按次数降序):');
|
|
74
|
-
for (const [name, n] of fs.sort((a, b) => b[1] - a[1])) lines.push(` ${name.padEnd(28)} ${String(n).padStart(7)} 次`);
|
|
75
|
-
}
|
|
76
|
-
process.stderr.write(`${lines.join('\n')}\n`);
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
// ─────────────────────────── 钩子线程:resolve / load ───────────────────────────
|
|
81
|
-
/** fs shim 的 URL:`node:fs` 与 `node:fs/promises` **必须分开两个 shim** —— 两者导出面重叠但不同
|
|
82
|
-
* (如 access),塞进同一模块会触发 conflicting star exports 语法错误(实测真实审计因此崩掉)。 */
|
|
83
|
-
const SHIM_FS = new URL('./hot-path-probe-fs-shim.mjs', import.meta.url).href;
|
|
84
|
-
const SHIM_FSP = new URL('./hot-path-probe-fsp-shim.mjs', import.meta.url).href;
|
|
85
|
-
|
|
86
|
-
let hookCfg = {};
|
|
87
|
-
/** Node 在钩子线程启动时调用,data 即主线程 register 传的配置。 */
|
|
88
|
-
export function initialize(data) {
|
|
89
|
-
hookCfg = data || {};
|
|
90
|
-
}
|
|
91
|
-
|
|
92
|
-
/** 重定向 fs 到对应 shim(用于统计 I/O 次数)。 */
|
|
93
|
-
export async function resolve(specifier, context, next) {
|
|
94
|
-
// ⚠️ 必须放行 **shim 自己**对 builtin 的 import:否则会把 shim 重定向到 shim,成环且静默埋雷
|
|
95
|
-
// (实测:负载不碰 fs 时看不出问题,一旦真用 fs 就会炸)。
|
|
96
|
-
const fromShim = context?.parentURL === SHIM_FS || context?.parentURL === SHIM_FSP;
|
|
97
|
-
if (!fromShim && hookCfg.fs !== false) {
|
|
98
|
-
if (specifier === 'node:fs') return { url: SHIM_FS, format: 'module', shortCircuit: true };
|
|
99
|
-
if (specifier === 'node:fs/promises') return { url: SHIM_FSP, format: 'module', shortCircuit: true };
|
|
100
|
-
}
|
|
101
|
-
return next(specifier, context);
|
|
102
|
-
}
|
|
103
|
-
|
|
104
|
-
/** 给目标模块源码追加「耗时 + 次数」包装(**ESM 与 CJS 自动判断**,用 loader 给的 format,不猜)。 */
|
|
105
|
-
export async function load(url, context, next) {
|
|
106
|
-
const r = await next(url, context);
|
|
107
|
-
const names = (hookCfg.modules || {})[url];
|
|
108
|
-
if (!Array.isArray(names) || !names.length) return r;
|
|
109
|
-
// format 由 Node 给出:'module' = ESM;'commonjs'(含 commonjs-typescript)= CJS;
|
|
110
|
-
// 其余(builtin / json / wasm 等)不处理——既不该改,也不适用下面两种包装。
|
|
111
|
-
const isEsm = r.format === 'module';
|
|
112
|
-
const isCjs = r.format === 'commonjs' || r.format === 'commonjs-typescript';
|
|
113
|
-
if (!isEsm && !isCjs) return r;
|
|
114
|
-
let src = r.source;
|
|
115
|
-
if (src && typeof src !== 'string') src = Buffer.from(src).toString('utf8');
|
|
116
|
-
if (typeof src !== 'string') return r;
|
|
117
|
-
|
|
118
|
-
// 计数容器 + 上报函数(两种格式共用;代码最终跑在主线程,故 globalThis 直接可读)
|
|
119
|
-
const header = '\nconst __HP = (globalThis.__HOT_PATH_PROBE__ ||= { fn: {}, fs: {} });\n'
|
|
120
|
-
+ 'function __hpRecord(__n, __ms) { const __e = (__HP.fn[__n] ||= { calls: 0, ms: 0 }); __e.calls += 1; __e.ms += __ms; }\n';
|
|
121
|
-
|
|
122
|
-
// ESM:模块**自己的函数声明绑定可变**(只有 import 进来的绑定只读)⇒ 模块内重赋值 import 方可见。
|
|
123
|
-
const esmSuffix = names.map((n) => `
|
|
124
|
-
;(() => {
|
|
125
|
-
const __orig = ${n};
|
|
126
|
-
if (typeof __orig !== 'function') return;
|
|
127
|
-
${n} = function (...__a) {
|
|
128
|
-
const __t0 = performance.now();
|
|
129
|
-
try { return __orig.apply(this, __a); }
|
|
130
|
-
finally { __hpRecord(${JSON.stringify(n)}, performance.now() - __t0); }
|
|
131
|
-
};
|
|
132
|
-
})();`).join('');
|
|
133
|
-
|
|
134
|
-
// CJS:同样重赋值本地函数声明(覆盖**内部调用**),并额外替换 `module.exports` 上**已导出**的引用
|
|
135
|
-
// —— CJS 常见 `module.exports = { foo }` 写在文件末尾,而本段代码追加在最后,
|
|
136
|
-
// 此时导出对象已捕获旧引用,故两处都要换。
|
|
137
|
-
const cjsSuffix = names.map((n) => `
|
|
138
|
-
;(() => {
|
|
139
|
-
const __orig = ${n};
|
|
140
|
-
if (typeof __orig !== 'function') return;
|
|
141
|
-
const __wrapped = function (...__a) {
|
|
142
|
-
const __t0 = performance.now();
|
|
143
|
-
try { return __orig.apply(this, __a); }
|
|
144
|
-
finally { __hpRecord(${JSON.stringify(n)}, performance.now() - __t0); }
|
|
145
|
-
};
|
|
146
|
-
${n} = __wrapped;
|
|
147
|
-
try {
|
|
148
|
-
if (typeof module !== 'undefined' && module.exports && module.exports.${n} === __orig) module.exports.${n} = __wrapped;
|
|
149
|
-
} catch { /* 只读导出(getter/冻结)忽略:内部调用已计数 */ }
|
|
150
|
-
})();`).join('');
|
|
151
|
-
|
|
152
|
-
return { ...r, source: src + header + (isEsm ? esmSuffix : cjsSuffix) };
|
|
153
|
-
}
|