dsh-git-push 0.0.0-stage → 2.8.4
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/.auditignore +30 -0
- package/.gitignore +39 -0
- package/LICENSE +21 -0
- package/README.md +1482 -2
- package/cli.mjs +360 -0
- package/cordis.patch.yml +14 -0
- package/lib/ARCHITECTURE.md +34 -0
- package/lib/BUGFIX-NOTES-2026-09-14.md +278 -0
- package/lib/app/apply.js +275 -0
- package/lib/app/audit-api.js +158 -0
- package/lib/app/command-registry.js +262 -0
- package/lib/app/constants.js +16 -0
- package/lib/app/handlers/account.js +166 -0
- package/lib/app/handlers/clone.js +168 -0
- package/lib/app/handlers/http-constants.js +9 -0
- package/lib/app/handlers/identity-rewrite.js +94 -0
- package/lib/app/handlers/meta.js +175 -0
- package/lib/app/handlers/npm.js +169 -0
- package/lib/app/handlers/repo-actions.js +143 -0
- package/lib/app/handlers/repos.js +231 -0
- package/lib/app/handlers/settings.js +62 -0
- package/lib/app/host-doc-checks.js +25 -0
- package/lib/app/http-handlers.js +131 -0
- package/lib/app/index.js +30 -0
- package/lib/app/inject-text.js +191 -0
- package/lib/app/scan-root.js +23 -0
- package/lib/app/schema.js +150 -0
- package/lib/app/settings-bridge.js +167 -0
- package/lib/app/slash-commands.js +395 -0
- package/lib/app/slot-stats.js +35 -0
- package/lib/app/tool-call.js +662 -0
- package/lib/app/tools.js +40 -0
- package/lib/ast/brace.js +105 -0
- package/lib/ast/callgraph.js +135 -0
- package/lib/ast/code-lines.js +114 -0
- package/lib/ast/consts.js +12 -0
- package/lib/ast/control-flow.js +461 -0
- package/lib/ast/credential.js +199 -0
- package/lib/ast/dataflow.js +274 -0
- package/lib/ast/dup-code.js +165 -0
- package/lib/ast/index.js +36 -0
- package/lib/ast/io-risk-const.js +95 -0
- package/lib/ast/io-risk-fn.js +208 -0
- package/lib/ast/io-risk-loop.js +308 -0
- package/lib/ast/io-risk.js +314 -0
- package/lib/ast/lang.js +156 -0
- package/lib/ast/line-count.js +52 -0
- package/lib/ast/magic-number.js +272 -0
- package/lib/ast/naming.js +284 -0
- package/lib/ast/perf.js +472 -0
- package/lib/ast/scope.js +241 -0
- package/lib/ast/shell.js +131 -0
- package/lib/ast/size.js +378 -0
- package/lib/ast/symbol-index.js +399 -0
- package/lib/ast/tokenizer.js +341 -0
- package/lib/audit/analysis-coverage.js +98 -0
- package/lib/audit/audit-file.js +182 -0
- package/lib/audit/checks.js +17 -0
- package/lib/audit/client-entry.js +93 -0
- package/lib/audit/collector.js +477 -0
- package/lib/audit/ext-runner.js +80 -0
- package/lib/audit/file-context.js +138 -0
- package/lib/audit/finding.js +50 -0
- package/lib/audit/gitignore-match.js +113 -0
- package/lib/audit/glob.js +63 -0
- package/lib/audit/history-report.js +100 -0
- package/lib/audit/history.js +126 -0
- package/lib/audit/ignore-blind.js +101 -0
- package/lib/audit/index.js +33 -0
- package/lib/audit/orchestrate.js +476 -0
- package/lib/audit/public.js +24 -0
- package/lib/audit/repo-level.js +30 -0
- package/lib/audit/report-yaml.js +86 -0
- package/lib/audit/slot.js +65 -0
- package/lib/audit-defaults.js +18 -0
- package/lib/audit-rules/audit-rules-comment.yml +247 -0
- package/lib/audit-rules/audit-rules-cpp.yml +22 -0
- package/lib/audit-rules/audit-rules-docs.yml +32 -0
- package/lib/audit-rules/audit-rules-dsh.yml +162 -0
- package/lib/audit-rules/audit-rules-filehealth.yml +42 -0
- package/lib/audit-rules/audit-rules-folder.yml +99 -0
- package/lib/audit-rules/audit-rules-frontend.yml +335 -0
- package/lib/audit-rules/audit-rules-go.yml +22 -0
- package/lib/audit-rules/audit-rules-i18n.yml +45 -0
- package/lib/audit-rules/audit-rules-java.yml +105 -0
- package/lib/audit-rules/audit-rules-nodejs.yml +647 -0
- package/lib/audit-rules/audit-rules-npm.yml +187 -0
- package/lib/audit-rules/audit-rules-paths.yml +92 -0
- package/lib/audit-rules/audit-rules-performance.yml +207 -0
- package/lib/audit-rules/audit-rules-php.yml +22 -0
- package/lib/audit-rules/audit-rules-private.yml +24 -0
- package/lib/audit-rules/audit-rules-python.yml +106 -0
- package/lib/audit-rules/audit-rules-robustness.yml +27 -0
- package/lib/audit-rules/audit-rules-rust.yml +22 -0
- package/lib/audit-rules/audit-rules-structure.yml +159 -0
- package/lib/audit-rules/audit-rules-swift.yml +22 -0
- package/lib/audit-rules/audit-rules-template.yml +108 -0
- package/lib/checks/button-bind.js +276 -0
- package/lib/checks/common.js +170 -0
- package/lib/checks/credential-file.js +43 -0
- package/lib/checks/dataflow.js +40 -0
- package/lib/checks/dispatch.js +112 -0
- package/lib/checks/dup-code.js +69 -0
- package/lib/checks/dup-const.js +232 -0
- package/lib/checks/file-health.js +150 -0
- package/lib/checks/filter.js +131 -0
- package/lib/checks/folder.js +173 -0
- package/lib/checks/hardcoded-path.js +98 -0
- package/lib/checks/index.js +46 -0
- package/lib/checks/io.js +66 -0
- package/lib/checks/magic-number.js +42 -0
- package/lib/checks/npm-json.js +273 -0
- package/lib/checks/private.js +63 -0
- package/lib/checks/regex.js +256 -0
- package/lib/checks/semantic.js +134 -0
- package/lib/checks/structural.js +274 -0
- package/lib/cli/commands-account.mjs +107 -0
- package/lib/cli/commands-audit.mjs +144 -0
- package/lib/cli/commands-doc.mjs +127 -0
- package/lib/cli/commands-vcs.mjs +175 -0
- package/lib/client/index.js +162 -0
- package/lib/client-parts/00-loader.js +33 -0
- package/lib/client-parts/01-const.js +207 -0
- package/lib/client-parts/02-utils.js +62 -0
- package/lib/client-parts/03-icons.js +12 -0
- package/lib/client-parts/10-account.js +83 -0
- package/lib/client-parts/11-browser.js +95 -0
- package/lib/client-parts/20-repo.js +374 -0
- package/lib/client-parts/21-audit.js +301 -0
- package/lib/client-parts/22-settings.js +146 -0
- package/lib/client-parts/23-npm.js +383 -0
- package/lib/client-parts/30-page.js +56 -0
- package/lib/client-parts/40-controller.js +1092 -0
- package/lib/client-parts/41-actions.js +279 -0
- package/lib/client-parts/99-apply.js +72 -0
- package/lib/client.js +3195 -0
- package/lib/commit-push.js +144 -0
- package/lib/context/index.js +363 -0
- package/lib/core/atomic-json.js +98 -0
- package/lib/core/config.js +40 -0
- package/lib/core/credentials.js +274 -0
- package/lib/core/endpoints.js +109 -0
- package/lib/core/exec.js +162 -0
- package/lib/exempt/index.js +292 -0
- package/lib/fs/edit-after-read.js +103 -0
- package/lib/fsx.js +87 -0
- package/lib/git/account-status.js +140 -0
- package/lib/git/account.js +233 -0
- package/lib/git/api.js +136 -0
- package/lib/git/atomic-json.js +6 -0
- package/lib/git/browse.js +38 -0
- package/lib/git/clone-download.js +397 -0
- package/lib/git/clone-history-mode.js +143 -0
- package/lib/git/clone-history.js +175 -0
- package/lib/git/clone-jobs.js +250 -0
- package/lib/git/clone-replay-io.js +172 -0
- package/lib/git/clone-replay.js +275 -0
- package/lib/git/clone.js +445 -0
- package/lib/git/cloud.js +46 -0
- package/lib/git/commit-message.js +141 -0
- package/lib/git/config.js +6 -0
- package/lib/git/cred-env.js +88 -0
- package/lib/git/credentials.js +6 -0
- package/lib/git/endpoints.js +6 -0
- package/lib/git/exec.js +6 -0
- package/lib/git/identity-rewrite.js +297 -0
- package/lib/git/identity.js +150 -0
- package/lib/git/ignore.js +69 -0
- package/lib/git/index.js +41 -0
- package/lib/git/module-splitter.js +47 -0
- package/lib/git/post-push.js +101 -0
- package/lib/git/push-diagnose.js +142 -0
- package/lib/git/push.js +470 -0
- package/lib/git/remote-resolve.js +146 -0
- package/lib/git/remote.js +128 -0
- package/lib/git/repo-index.js +512 -0
- package/lib/git/repos.js +235 -0
- package/lib/git/scan-runner.js +159 -0
- package/lib/git/sensitive.js +134 -0
- package/lib/git/transport.js +430 -0
- package/lib/git/visibility.js +35 -0
- package/lib/git/wrapped-git.js +68 -0
- package/lib/http/index.js +170 -0
- package/lib/index.js +24 -0
- package/lib/link-check/index.js +187 -0
- package/lib/npm/account.js +64 -0
- package/lib/npm/install.js +211 -0
- package/lib/npm/npmrc.js +56 -0
- package/lib/npm/publish.js +167 -0
- package/lib/npm/registry.js +147 -0
- package/lib/plugin/auto-detect.js +92 -0
- package/lib/plugin/auto-push.js +154 -0
- package/lib/plugin/index.js +250 -0
- package/lib/readme-templates/readme.yml +38 -0
- package/lib/rule/compilers/credential.js +62 -0
- package/lib/rule/compilers/dataflow.js +38 -0
- package/lib/rule/compilers/file-health.js +75 -0
- package/lib/rule/compilers/frontend.js +86 -0
- package/lib/rule/compilers/func.js +35 -0
- package/lib/rule/compilers/helpers.js +71 -0
- package/lib/rule/compilers/index.js +29 -0
- package/lib/rule/compilers/link-semantic.js +45 -0
- package/lib/rule/compilers/list-kinds.js +12 -0
- package/lib/rule/compilers/numeric-kinds.js +66 -0
- package/lib/rule/compilers/regex.js +78 -0
- package/lib/rule/compilers/structure.js +80 -0
- package/lib/rule/compilers.js +17 -0
- package/lib/rule/homoglyph.js +45 -0
- package/lib/rule/loader.js +270 -0
- package/lib/rule/registry.js +115 -0
- package/lib/rule/scope.js +67 -0
- package/lib/score/docs-score.js +166 -0
- package/lib/score/index.js +140 -0
- package/lib/self/index.js +193 -0
- package/lib/skip-dirs.js +64 -0
- package/lib/tool-probes.json +50 -0
- package/lib/user-requirements.json +14 -0
- package/lib/vendor/js-yaml/LICENSE +21 -0
- package/lib/vendor/js-yaml/js-yaml.mjs +3073 -0
- package/package.json +95 -4
- package/scripts/__pycache__/module-splitter.cpython-38.pyc +0 -0
- package/scripts/audit-ext/_example-readme-present.mjs +34 -0
- package/scripts/audit-ext/variable-min-length.mjs +102 -0
- package/scripts/audit-runner.mjs +35 -0
- package/scripts/audit-runtime-check.mjs +129 -0
- package/scripts/browser-page-probe.mjs +271 -0
- package/scripts/build-client.mjs +119 -0
- package/scripts/check.mjs +88 -0
- package/scripts/clean-date-comments.py +102 -0
- package/scripts/doc-drift.mjs +200 -0
- package/scripts/doc-func.mjs +212 -0
- package/scripts/doc-tree.mjs +456 -0
- package/scripts/doc-version.mjs +220 -0
- package/scripts/frontend-preview-check.mjs +124 -0
- package/scripts/hot-path-probe-cjs.cjs +71 -0
- package/scripts/hot-path-probe-fs-shim.mjs +28 -0
- package/scripts/hot-path-probe-fsp-shim.mjs +31 -0
- package/scripts/hot-path-probe.mjs +153 -0
- package/scripts/module-splitter.py +800 -0
- package/scripts/platform-scan.mjs +168 -0
- package/scripts/preview-gen.mjs +489 -0
- package/scripts/preview-local-runner.mjs +55 -0
- package/scripts/preview-server-direct.mjs +116 -0
- package/scripts/preview-server.mjs +305 -0
- package/scripts/preview-slot-data.mjs +123 -0
- package/scripts/probe-recheck.mjs +47 -0
- package/scripts/readme-gen.mjs +268 -0
- package/scripts/rename-locator.mjs +97 -0
- package/scripts/rule-switch.mjs +97 -0
- package/scripts/rules-solo-audit.mjs +173 -0
- package/scripts/scan-file-io.mjs +713 -0
- package/scripts/scan-hardcoded-paths.mjs +125 -0
- package/scripts/scan-repos.mjs +167 -0
- package/scripts/scan-version.mjs +122 -0
- package/scripts/scrub-user-wording.mjs +420 -0
- package/scripts/symbol-index.mjs +85 -0
- package/scripts/sync-plugin-install.mjs +223 -0
- package/scripts/sync-plugin.mjs +279 -0
- package/scripts/verify-prestep.mjs +100 -0
- package/skills/dev/audit-rule-authoring.md +58 -0
- package/skills/dev/dsh-git-push.md +323 -0
- package/skills/dev/git-push-live-fix.md +45 -0
- package/skills/dsh-repo-index.md +35 -0
- package/skills/guide/guide-audit.md +167 -0
- package/skills/guide/guide-cli-scripts.md +104 -0
- package/skills/guide/guide-clone-repos.md +173 -0
- package/skills/guide/guide-commit-push.md +156 -0
- package/skills/guide/guide-inject-ui.md +166 -0
- package/skills/guide/guide-slash-completion.md +118 -0
- package/skills/workflow/README.md +21 -0
- package/skills/workflow/git-commit-discipline.md +68 -0
- package/skills/workflow/git-project-startup.md +85 -0
- package/skills/workflow/git-rebuild-process.md +57 -0
- package/skills/workflow/github-operations.md +91 -0
- package/skills/workflow/readme-sync-git-md.md +28 -0
- package/skills/workflow/task-completion-report.md +73 -0
- package/skills/workflow/tool-json-add-ask.md +35 -0
- package/skills/workflow/versioning-rule.md +211 -0
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* dsh-git-push — 版本列表文档生成器(doc-version:版本表由 git log 权威生成,聚合入表防手写版本记录漂移)
|
|
4
|
+
* dsh-skip-i18n: 用户可见文案硬编码为产品设计
|
|
5
|
+
*
|
|
6
|
+
* 分体式文档三兄弟之一(doc-tree 文件树 / doc-func 函数列表 / doc-version 版本列表)。
|
|
7
|
+
* 从 git log 聚合提交标题里的 X.Y.Z 版本号,生成版本记录表 markdown,
|
|
8
|
+
* 写入宿主 md(README 有 dshgp-version 标记块用 README,否则 docs/ 带块 md)。
|
|
9
|
+
* 复用 readme-gen.mjs 的 buildReadmeVersionTable(版本聚合逻辑单一事实源)。
|
|
10
|
+
*
|
|
11
|
+
* 用法:
|
|
12
|
+
* node scripts/doc-version.mjs gen [--root <项目根>] # 打印版本表文本
|
|
13
|
+
* node scripts/doc-version.mjs apply [--root <项目根>] # 写入宿主 md(自动探测)
|
|
14
|
+
* node scripts/doc-version.mjs check [--root <项目根>] # 比对宿主块与最新(漂移报错)
|
|
15
|
+
*/
|
|
16
|
+
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
|
|
17
|
+
import { join, resolve, relative, basename, dirname } from 'node:path';
|
|
18
|
+
import { fileURLToPath } from 'node:url';
|
|
19
|
+
import { findMarkedHostMd } from './doc-tree.mjs';
|
|
20
|
+
import { buildReadmeVersionTable } from './readme-gen.mjs';
|
|
21
|
+
|
|
22
|
+
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
23
|
+
const MARKER = 'dshgp-version';
|
|
24
|
+
const MARK_START = `<!-- ${MARKER}:start -->`;
|
|
25
|
+
const MARK_END = `<!-- ${MARKER}:end -->`;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* 版本表「最新行」的来源:
|
|
29
|
+
* · npm 项目(项目根有 package.json)默认取 package.json.version —— 它才是版本号权威源
|
|
30
|
+
* (scan-version 门禁也正是比对 package.json),因此发版流程无需「先提交再生成再 amend」;
|
|
31
|
+
* · 其余项目退回 git log 聚合(老项目行为不变)。
|
|
32
|
+
* @param {string} root 项目根
|
|
33
|
+
* @param {string} [explicit] 'package.json' | 'git-log'(显式覆盖,留空则自动识别)
|
|
34
|
+
*/
|
|
35
|
+
/* 旧的 resolveVersionSource 已删除:它只判断"有没有 package.json",
|
|
36
|
+
已被下方 detectVersionSource/projectVersionOf 版本取代(非 npm 项目需按类型识别)。 */
|
|
37
|
+
|
|
38
|
+
/** 读项目 package.json 的 version;读不到返回空串(不抛错,退回 git log 行)。 */
|
|
39
|
+
/** 支持的项目类型 → 版本文件(数组顺序即探测优先级)。
|
|
40
|
+
* ⚠️ 为什么需要这个表:只判断"有没有 package.json"会把非 npm 项目误判为 git-log 聚合
|
|
41
|
+
* (用户指出:package.json 只是 **npm 项目的默认源**,工具应能识别项目类型自动切换)。 */
|
|
42
|
+
const VERSION_SOURCES = [
|
|
43
|
+
{ id: 'package.json', file: 'package.json', read: (t) => JSON.parse(t).version },
|
|
44
|
+
{ id: 'pyproject.toml', file: 'pyproject.toml', read: (t) => (t.match(/^\s*version\s*=\s*["']([^"']+)["']/m) || [])[1] },
|
|
45
|
+
{ id: 'Cargo.toml', file: 'Cargo.toml', read: (t) => (t.match(/^\s*version\s*=\s*["']([^"']+)["']/m) || [])[1] },
|
|
46
|
+
{ id: 'composer.json', file: 'composer.json', read: (t) => JSON.parse(t).version },
|
|
47
|
+
{ id: 'setup.cfg', file: 'setup.cfg', read: (t) => (t.match(/^\s*version\s*=\s*([^\s#]+)/m) || [])[1] },
|
|
48
|
+
];
|
|
49
|
+
|
|
50
|
+
/** 按项目类型探测版本源;都不匹配则回退 git-log 聚合(老项目行为不变)。 */
|
|
51
|
+
export function detectVersionSource(root) {
|
|
52
|
+
for (const s of VERSION_SOURCES) {
|
|
53
|
+
if (existsSync(join(root, s.file))) return s.id;
|
|
54
|
+
}
|
|
55
|
+
return 'git-log';
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** 版本源解析:显式指定优先;否则按项目类型自动识别。 */
|
|
59
|
+
export function resolveVersionSource(root, explicit = '') {
|
|
60
|
+
if (explicit) return explicit;
|
|
61
|
+
return detectVersionSource(root);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** 按已识别/指定的版本源读取版本号;读不到返回空串(不抛错,退回 git log 行)。 */
|
|
65
|
+
export function projectVersionOf(root, source = '') {
|
|
66
|
+
const src = source || detectVersionSource(root);
|
|
67
|
+
const def = VERSION_SOURCES.find((s) => s.id === src);
|
|
68
|
+
if (!def) return '';
|
|
69
|
+
try {
|
|
70
|
+
const v = def.read(readFileSync(join(root, def.file), 'utf8'));
|
|
71
|
+
return v ? String(v).trim() : '';
|
|
72
|
+
} catch {
|
|
73
|
+
return '';
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** 兼容旧调用:等价于"按项目类型识别后取版本号"。 */
|
|
78
|
+
export function packageVersionOf(root) {
|
|
79
|
+
return projectVersionOf(root, detectVersionSource(root));
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/** 生成版本列表 markdown(宿主块内容)。 */
|
|
83
|
+
export function buildVersionListText(root, { versionSource = '' } = {}) {
|
|
84
|
+
const rows = buildReadmeVersionTable(root);
|
|
85
|
+
const source = resolveVersionSource(root, versionSource);
|
|
86
|
+
const pkg = source !== 'git-log' ? projectVersionOf(root, source) : '';
|
|
87
|
+
// 只改**最新数据行**的版本号(rows[0]=表头、rows[1]=分隔行 ⇒ 数据从 rows[2] 起);
|
|
88
|
+
// 日期与标题仍来自该行原本的 git 提交 —— 历史行完全不动。
|
|
89
|
+
if (pkg && rows.length > 2) {
|
|
90
|
+
const m = rows[2].match(/\d+\.\d+\.\d+/);
|
|
91
|
+
if (m && m[0] !== pkg) rows[2] = rows[2].replace(m[0], pkg);
|
|
92
|
+
} else if (pkg) {
|
|
93
|
+
// 版本真源是 package.json:**git log 读不到时也必须出表**(此前这里产 0 行 ⇒ 整张表被写空)。
|
|
94
|
+
// 提交历史不可读时,至少以 package.json 的版本号生成一条数据行,绝不产出空表。
|
|
95
|
+
rows.push(`| ${pkg} | 版本号来自 package.json(提交历史不可读,内容待补) |`);
|
|
96
|
+
}
|
|
97
|
+
// ── 发布说明源(docs/releases.json):拆掉「最新行只能来自 git log」这个环 ──
|
|
98
|
+
// 历史行的标题/日期仍来自 git log(无需维护);**当前版本**的标题可由本文件提供 ⇒
|
|
99
|
+
// `apply`/`check` 在提交前就能产出与提交后**完全一致**的表,发版不再需要「先提交再生成再 amend」。
|
|
100
|
+
// 取值优先级:本文件的当前版本标题 > git log 里同名版本行 > git log 最新行(版本号按 package.json 覆盖)。
|
|
101
|
+
const releaseTitle = (() => {
|
|
102
|
+
try {
|
|
103
|
+
const p = join(root, 'docs', 'releases.json');
|
|
104
|
+
if (!existsSync(p)) return '';
|
|
105
|
+
const j = JSON.parse(readFileSync(p, 'utf8'));
|
|
106
|
+
const v = j && typeof j === 'object' ? j[pkg] : '';
|
|
107
|
+
return typeof v === 'string' ? v.trim() : '';
|
|
108
|
+
} catch {
|
|
109
|
+
return ''; // 文件缺失/非法 JSON:静默退回纯 git log 行为(不因辅助源报错而阻断发版)
|
|
110
|
+
}
|
|
111
|
+
})();
|
|
112
|
+
if (pkg && releaseTitle) {
|
|
113
|
+
if (rows.length > 2) {
|
|
114
|
+
const cells = rows[2].split('|').map((s) => s.trim());
|
|
115
|
+
if (cells[1] === pkg) rows[2] = `| ${pkg} | ${releaseTitle} |`; // 版本已在 git log:只换标题
|
|
116
|
+
else rows.splice(2, 0, `| ${pkg} | ${releaseTitle} |`); // git log 尚无该版本:插入为最新行
|
|
117
|
+
} else {
|
|
118
|
+
rows.push(`| ${pkg} | ${releaseTitle} |`); // 提交历史不可读:至少出这一行
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
return { text: `## 版本列表\n\n${rows.join('\n')}\n`, rows: rows.length - 2, source, packageVersion: pkg };
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** 找宿主 md 内的 dshgp-version 标记块。 */
|
|
125
|
+
function findBlock(text) {
|
|
126
|
+
const s = text.indexOf(MARK_START);
|
|
127
|
+
const e = text.indexOf(MARK_END);
|
|
128
|
+
if (s === -1 || e === -1 || e <= s) return null;
|
|
129
|
+
return { start: s, end: e, content: text.slice(s + MARK_START.length, e) };
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** 替换/插入标记块。无块时追加到文件尾。 */
|
|
133
|
+
export function applyVersionBlock(text, newContent) {
|
|
134
|
+
const block = findBlock(text);
|
|
135
|
+
if (block) return text.slice(0, block.start) + MARK_START + '\n' + newContent + '\n' + MARK_END + text.slice(block.end + MARK_END.length);
|
|
136
|
+
return text.replace(/\s*$/, '\n') + `\n${MARK_START}\n${newContent}\n${MARK_END}\n`;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** 比对宿主块与最新版本表。返回 { ok, issues, latest }。 */
|
|
140
|
+
export function checkVersionDrift({ hostPath, root, versionSource = '' } = {}) {
|
|
141
|
+
const { text: latest, source } = buildVersionListText(root, { versionSource });
|
|
142
|
+
const host = existsSync(hostPath) ? readFileSync(hostPath, 'utf8') : '';
|
|
143
|
+
const block = findBlock(host);
|
|
144
|
+
const issues = [];
|
|
145
|
+
if (!block) issues.push({ type: 'no-block', msg: `${basename(hostPath)} 无版本列表标记块(${MARK_START} … ${MARK_END}),先 apply 生成` });
|
|
146
|
+
else if (block.content.trim() !== latest.trim()) issues.push({ type: 'drift', msg: `版本列表与期望内容不一致(来源:${source},运行 doc-version.mjs apply 更新)` });
|
|
147
|
+
return { ok: issues.length === 0, issues, latest, source };
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/* ─────────── CLI ─────────── */
|
|
151
|
+
|
|
152
|
+
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
153
|
+
const args = process.argv.slice(2);
|
|
154
|
+
const cmd = args[0];
|
|
155
|
+
const rootIdx = args.indexOf('--root');
|
|
156
|
+
const root = rootIdx !== -1 && args[rootIdx + 1] ? resolve(args[rootIdx + 1]) : ROOT;
|
|
157
|
+
// 版本来源可显式指定(package.json | git-log);不传则按项目类型自动识别(有 package.json 即 npm 项目)
|
|
158
|
+
const srcIdx = args.indexOf('--version-source');
|
|
159
|
+
const versionSource = srcIdx !== -1 && args[srcIdx + 1] ? String(args[srcIdx + 1]) : '';
|
|
160
|
+
if (versionSource && versionSource !== 'package.json' && versionSource !== 'git-log') {
|
|
161
|
+
console.log(`❌ --version-source 只接受 package.json 或 git-log,收到:${versionSource}`);
|
|
162
|
+
process.exit(1);
|
|
163
|
+
}
|
|
164
|
+
const host = findMarkedHostMd(root, MARKER);
|
|
165
|
+
const out = (msg) => console.log(msg);
|
|
166
|
+
|
|
167
|
+
if (cmd === 'gen') {
|
|
168
|
+
const r = buildVersionListText(root, { versionSource });
|
|
169
|
+
out(r.text);
|
|
170
|
+
out(`\n(${r.rows} 版本行;来源 ${r.source};apply 写入 ${relative(root, host) || 'README.md'})`);
|
|
171
|
+
process.exit(0);
|
|
172
|
+
}
|
|
173
|
+
if (cmd === 'apply') {
|
|
174
|
+
const r = buildVersionListText(root, { versionSource });
|
|
175
|
+
const hostText = existsSync(host) ? readFileSync(host, 'utf8') : '';
|
|
176
|
+
const force = args.includes('--force');
|
|
177
|
+
// ── 预演(dry-run):先看清"将写入几行、首行是什么",再决定落盘 ──
|
|
178
|
+
// 破坏性写入前必须能预演;`gen` 也能看内容,但 dry-run 额外报出目标文件与现有行数对比。
|
|
179
|
+
if (args.includes('--dry-run')) {
|
|
180
|
+
const curB = findBlock(hostText);
|
|
181
|
+
const curN = curB ? (curB.content.match(/^\|\s*\d+\.\d+\.\d+\s*\|/gm) || []).length : 0;
|
|
182
|
+
out(`[dry-run] 目标文件:${relative(root, host) || 'README.md'}`);
|
|
183
|
+
out(`[dry-run] 将写入:${r.rows} 版本行(来源 ${r.source});现有:${curN} 行`);
|
|
184
|
+
out(`[dry-run] 首行预览:${(r.text.split('\n').find((l) => /^\|\s*\d/.test(l)) || '(无数据行)').trim()}`);
|
|
185
|
+
out('[dry-run] 未做任何写入。');
|
|
186
|
+
process.exit(0);
|
|
187
|
+
}
|
|
188
|
+
// ── 安全闸(2026-10-10 真实事故:本工具静默把整张版本表清空)──
|
|
189
|
+
// 0 行的常见原因**不是**"项目真的没有版本",而是 git log 读不到(如本机 dubious ownership,
|
|
190
|
+
// git 直接拒绝该仓库)⇒ 此时必须拒绝写盘,绝不覆盖现有版本表。
|
|
191
|
+
if (!force && !(r.rows > 0)) {
|
|
192
|
+
out(`❌ 拒绝写盘:聚合出 0 条版本行(来源 ${r.source})——现有版本表保持不变,未做任何修改。`);
|
|
193
|
+
out(' 常见原因:git log 读不到该仓库(例如 dubious ownership 被 git 拒绝)。先执行:');
|
|
194
|
+
out(" git config --global --add safe.directory '*'");
|
|
195
|
+
out(' 再用 `node scripts/doc-version.mjs gen` 确认能输出真实版本行(非 0 行)后重试;');
|
|
196
|
+
out(' 确实要写空表时显式加 --force。');
|
|
197
|
+
process.exit(2);
|
|
198
|
+
}
|
|
199
|
+
// ── 骤减保护:新表行数少于现有表行数 ⇒ 疑似聚合来源异常(log 不完整/换源),同样拒绝写盘 ──
|
|
200
|
+
const curBlock = findBlock(hostText);
|
|
201
|
+
const curRows = curBlock ? (curBlock.content.match(/^\|\s*\d+\.\d+\.\d+\s*\|/gm) || []).length : 0;
|
|
202
|
+
if (!force && curRows > 0 && r.rows < curRows) {
|
|
203
|
+
out(`❌ 拒绝写盘:本次聚合 ${r.rows} 行 < 现有 ${curRows} 行(疑似聚合来源异常,如 git log 不完整或换源)。`);
|
|
204
|
+
out(' 现有版本表保持不变;确认要缩减请先备份,再显式加 --force。');
|
|
205
|
+
process.exit(2);
|
|
206
|
+
}
|
|
207
|
+
writeFileSync(host, applyVersionBlock(hostText, r.text), 'utf8');
|
|
208
|
+
out(`✅ 已写入版本列表 → ${relative(root, host) || 'README.md'}(${r.rows} 版本行;来源 ${r.source})`);
|
|
209
|
+
process.exit(0);
|
|
210
|
+
}
|
|
211
|
+
if (cmd === 'check') {
|
|
212
|
+
const r = checkVersionDrift({ hostPath: host, root, versionSource });
|
|
213
|
+
if (r.ok) { out(`✅ 版本列表一致(来源 ${r.source})`); process.exit(0); }
|
|
214
|
+
out('❌ 版本列表存在差异:');
|
|
215
|
+
for (const i of r.issues) out(' - ' + i.msg);
|
|
216
|
+
process.exit(1);
|
|
217
|
+
}
|
|
218
|
+
out('用法: node scripts/doc-version.mjs <gen|apply|check> [--root <项目根>] [--version-source package.json|git-log]');
|
|
219
|
+
process.exit(1);
|
|
220
|
+
}
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 前端渲染自检(clone 预览弹窗)——把「改前端后必须实际看一眼」变成一条可重复命令。
|
|
3
|
+
*
|
|
4
|
+
* 为什么需要:宿主 GUI 里看插件页面要刷新/重启,前端报错又只藏在浏览器控制台;
|
|
5
|
+
* 而 clone 预览弹窗只在「真实交互走到那一步」时才出现(面板状态由构造函数初始化,
|
|
6
|
+
* 外部注入的终态会被覆盖)⇒ 必须**驱动**而不是塞状态。
|
|
7
|
+
*
|
|
8
|
+
* 依赖(都按环境变量传入,脚本内不写死绝对路径):
|
|
9
|
+
* PW_ROOT 含 node_modules/playwright 的目录(createRequire 的基准)
|
|
10
|
+
* CHROMIUM 无头浏览器可执行文件(chrome-headless-shell 亦可)
|
|
11
|
+
* 运行库/字体由调用方通过 LD_LIBRARY_PATH / FONTCONFIG_FILE 提供(无头 chromium 的既有要求)
|
|
12
|
+
*
|
|
13
|
+
* 用法(⚠️ 两个实测坑,都踩过):
|
|
14
|
+
* node scripts/frontend-preview-check.mjs --html "$PWD/assets/preview.html?mock=1" [--out <截图.png>]
|
|
15
|
+
* · --html 必须给**绝对路径**(或自带 file://):相对路径会让 page.goto 直接 ERR_INVALID_URL。
|
|
16
|
+
* · 建议带 `?mock=1`:预览页切内置假数据(见 README「离线调试」)。不带时页面 fetch 真后端,
|
|
17
|
+
* /repos-cloud 等返回 404 ⇒ 报「仓库列表没有 clone 按钮」这类**假失败**(看着像前端坏了,其实是没数据)。
|
|
18
|
+
* 运行前需 PW_ROOT(含 node_modules/playwright 的目录)+ CHROMIUM(无头浏览器),
|
|
19
|
+
* 运行库/字体由调用方通过 LD_LIBRARY_PATH / FONTCONFIG_FILE 提供(无头 chromium 的既有要求)。
|
|
20
|
+
* 前置(生成预览页;同样由调用方给出工具与 React UMD 路径):
|
|
21
|
+
* <dsh>/skills/frontend-real-render-preview.mjs --client lib/client.js --out <预览页.html>
|
|
22
|
+
* --react <dsh>/cache/react-umd --endpoints <伪造响应.json>
|
|
23
|
+
* 伪造响应至少含三组:/repos-cloud、/browse、/clone-preview(形状见测试用例的断言数据)。
|
|
24
|
+
*
|
|
25
|
+
* 判据(任一不满足即非零退出):
|
|
26
|
+
* ① 云端标签 → ② 加载仓库列表 → ③ 行内 clone → ④ 目录选择器确认 → ⑤ 预览弹窗出现
|
|
27
|
+
* ⑥ 弹窗内「带真实历史」勾选框存在、且默认 checked=true(与后端默认一致)
|
|
28
|
+
* ⑦ 全程无前端错误(pageerror / console.error)
|
|
29
|
+
*/
|
|
30
|
+
import { createRequire } from 'node:module';
|
|
31
|
+
|
|
32
|
+
const argv = process.argv.slice(2);
|
|
33
|
+
const arg = (name, def = '') => {
|
|
34
|
+
const i = argv.indexOf(name);
|
|
35
|
+
return i >= 0 && argv[i + 1] ? argv[i + 1] : def;
|
|
36
|
+
};
|
|
37
|
+
const HTML = arg('--html');
|
|
38
|
+
const OUT = arg('--out', 'frontend-preview-check.png');
|
|
39
|
+
// plain = 普通克隆(伪造 /clone-preview 里 partial:false):不应出现「重来」
|
|
40
|
+
// partial = 不完整克隆(partial:true):应出现「重来」与 partial 提示
|
|
41
|
+
const EXPECT = arg('--expect', 'plain');
|
|
42
|
+
const PW_ROOT = process.env.PW_ROOT || process.cwd();
|
|
43
|
+
const CHROME = process.env.CHROMIUM || '';
|
|
44
|
+
if (!HTML) { console.error('缺少 --html <预览页.html>'); process.exit(2); }
|
|
45
|
+
if (!CHROME) { console.error('缺少环境变量 CHROMIUM(无头浏览器可执行文件路径)'); process.exit(2); }
|
|
46
|
+
|
|
47
|
+
const require = createRequire(PW_ROOT.replace(/\/?$/, '/'));
|
|
48
|
+
const { chromium } = require('playwright');
|
|
49
|
+
|
|
50
|
+
const browser = await chromium.launch({
|
|
51
|
+
executablePath: CHROME,
|
|
52
|
+
// file:// 页面要能 fetch 真后端/伪造端点:与 frontend-real-render-preview 的 --open 同参数
|
|
53
|
+
args: ['--no-sandbox', '--disable-gpu', '--disable-web-security', '--allow-file-access-from-files'],
|
|
54
|
+
});
|
|
55
|
+
const page = await browser.newPage({ viewport: { width: 1320, height: 1000 } });
|
|
56
|
+
const errs = [];
|
|
57
|
+
page.on('pageerror', (e) => errs.push('pageerror: ' + e.message.slice(0, 120)));
|
|
58
|
+
page.on('console', (m) => { if (m.type() === 'error') errs.push('console: ' + m.text().slice(0, 140)); });
|
|
59
|
+
|
|
60
|
+
const clickText = async (re) => {
|
|
61
|
+
const b = page.locator('button', { hasText: re }).first();
|
|
62
|
+
if (await b.count()) { await b.click({ timeout: 4000 }).catch(() => {}); await page.waitForTimeout(2200); return true; }
|
|
63
|
+
return false;
|
|
64
|
+
};
|
|
65
|
+
const fails = [];
|
|
66
|
+
const need = (cond, msg) => { if (!cond) fails.push(msg); };
|
|
67
|
+
|
|
68
|
+
await page.goto('file://' + HTML, { waitUntil: 'load' });
|
|
69
|
+
await page.waitForTimeout(2200);
|
|
70
|
+
|
|
71
|
+
need(await clickText(/^云端$/), '未找到「云端」标签');
|
|
72
|
+
need(await clickText(/加载仓库列表/), '未找到「加载仓库列表」按钮');
|
|
73
|
+
const clones = page.locator('button', { hasText: /^clone$/ });
|
|
74
|
+
need(await clones.count() > 0, '仓库列表没有出现 clone 按钮(伪造 /repos-cloud 或 /browse 响应不符)');
|
|
75
|
+
if (await clones.count()) {
|
|
76
|
+
await clones.first().click().catch(() => {});
|
|
77
|
+
await page.waitForTimeout(2600);
|
|
78
|
+
if (!(await clickText(/选择当前目录|确定|选择|确认|此目录|开始/))) {
|
|
79
|
+
const row = page.locator('text=dshgp-demo').first();
|
|
80
|
+
if (await row.count()) { await row.click().catch(() => {}); await page.waitForTimeout(1200); await clickText(/选择当前目录|确定|选择|确认|此目录|开始/); }
|
|
81
|
+
else fails.push('目录选择器里既没有确认按钮也没有可点目录');
|
|
82
|
+
}
|
|
83
|
+
await page.waitForTimeout(2500);
|
|
84
|
+
}
|
|
85
|
+
const dlg = page.locator('.dshgp_clonepreview');
|
|
86
|
+
const hasDlg = await dlg.count();
|
|
87
|
+
need(hasDlg > 0, 'clone 预览弹窗未出现(clone-preview 未被触发或响应不符)');
|
|
88
|
+
if (hasDlg) {
|
|
89
|
+
const box = page.locator('.dshgp_previewopt input[type=checkbox]');
|
|
90
|
+
need(await box.count() > 0, '弹窗内没有「带真实历史」勾选框(类名 .dshgp_previewopt 变了?)');
|
|
91
|
+
if (await box.count()) {
|
|
92
|
+
const checked = await box.first().isChecked();
|
|
93
|
+
need(checked === true, `勾选框默认应为 checked=true(与后端默认「带历史」一致),实测 ${checked}`);
|
|
94
|
+
// 切换有效性:「取消勾选 ⇒ 真的传 history:false ⇒ 退回整树快照」依赖前端能切换成功,
|
|
95
|
+
// 故这里验「点一下真的变 false、再点回 true」;提交体是否带 history:false 由代码审查 + 用例覆盖。
|
|
96
|
+
await box.first().click().catch(() => {});
|
|
97
|
+
await page.waitForTimeout(600);
|
|
98
|
+
const off = await box.first().isChecked();
|
|
99
|
+
need(off === false, `点击勾选框应变为未勾选(实测 ${off})——说明 onChange 没接到或状态没重绘`);
|
|
100
|
+
await box.first().click().catch(() => {});
|
|
101
|
+
await page.waitForTimeout(600);
|
|
102
|
+
const back = await box.first().isChecked();
|
|
103
|
+
need(back === true, `再次点击应恢复勾选(实测 ${back})`);
|
|
104
|
+
}
|
|
105
|
+
// 条件渲染对照:「重来」按钮与 partial 提示只在「已存在且不完整」时出现。
|
|
106
|
+
// 只验出现态无法区分「只在 partial 时显示」与「总是显示」——故两种期望值都要能断言。
|
|
107
|
+
const labels = (await dlg.locator('button').allInnerTexts()).map((t) => t.trim());
|
|
108
|
+
const hasRestart = labels.includes('重来');
|
|
109
|
+
const hasHint = (await page.locator('.dshgp_previewpartial').count()) > 0;
|
|
110
|
+
if (EXPECT === 'partial') {
|
|
111
|
+
need(hasRestart, `不完整克隆应出现「重来」按钮(实测按钮 ${JSON.stringify(labels)})`);
|
|
112
|
+
need(hasHint, '不完整克隆应显示 partial 提示(.dshgp_previewpartial)');
|
|
113
|
+
} else {
|
|
114
|
+
need(!hasRestart, `普通克隆不应出现「重来」按钮(实测按钮 ${JSON.stringify(labels)})`);
|
|
115
|
+
need(!hasHint, '普通克隆不应显示 partial 提示');
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
await page.screenshot({ path: OUT, fullPage: true });
|
|
119
|
+
if (errs.length) fails.push('存在前端错误: ' + errs.slice(0, 2).join(' | '));
|
|
120
|
+
await browser.close();
|
|
121
|
+
|
|
122
|
+
console.log(fails.length ? '❌ 前端渲染自检未通过:\n - ' + fails.join('\n - ') + '\n 截图: ' + OUT
|
|
123
|
+
: '✅ 前端渲染自检通过(弹窗出现 + 勾选框存在 + 默认勾选 + 切换有效 + 无前端错误)\n 截图: ' + OUT);
|
|
124
|
+
process.exit(fails.length ? 1 : 0);
|
|
@@ -0,0 +1,71 @@
|
|
|
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
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
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');
|
|
@@ -0,0 +1,31 @@
|
|
|
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');
|
|
@@ -0,0 +1,153 @@
|
|
|
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
|
+
}
|