dsh-git-push 2.20.19 → 3.1.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 +76 -47
- package/cli-tool.mjs +2 -4
- package/cli.mjs +11 -4
- package/lib/app/apply.js +15 -13
- package/lib/app/command-registry.js +26 -19
- package/lib/app/handlers/http-constants.js +8 -0
- package/lib/app/handlers/meta.js +2 -2
- package/lib/app/handlers/preprocess.js +104 -0
- package/lib/app/handlers/repo-actions.js +2 -3
- package/lib/app/handlers/repos.js +137 -10
- package/lib/app/handlers/settings.js +34 -15
- package/lib/app/http-handlers.js +13 -42
- package/lib/app/index.js +3 -2
- package/lib/app/inject-text.js +6 -21
- package/lib/app/preprocess-client.js +136 -0
- package/lib/app/repo-ownership.js +1 -1
- package/lib/app/schema.js +20 -10
- package/lib/app/settings-bridge.js +60 -8
- package/lib/app/severity.js +14 -0
- package/lib/app/slash-commands.js +5 -164
- package/lib/app/tool-call.js +96 -163
- package/lib/cli/commands-preprocess.mjs +74 -0
- package/lib/cli/commands-tool.mjs +3 -2
- package/lib/cli/commands-vcs.mjs +39 -5
- package/lib/cli/shared.mjs +36 -10
- package/lib/client/index.js +11 -16
- package/lib/client-parts/git/account.js +21 -12
- package/lib/client-parts/git/actions.js +23 -77
- package/lib/client-parts/git/apply.js +8 -2
- package/lib/client-parts/git/browser.js +1 -1
- package/lib/client-parts/git/const.js +33 -1
- package/lib/client-parts/git/controller.js +175 -176
- package/lib/client-parts/git/icons.js +1 -1
- package/lib/client-parts/git/loader.js +1 -1
- package/lib/client-parts/git/npm.js +56 -37
- package/lib/client-parts/git/page.js +53 -1
- package/lib/client-parts/git/repo.js +8 -1
- package/lib/client-parts/git/settings.js +13 -1
- package/lib/client-parts/git/state.js +237 -0
- package/lib/client-parts/git/utils.js +1 -1
- package/lib/client.js +631 -312
- package/lib/commit-push/pre-commit-engine.js +629 -30
- package/lib/commit-push.js +127 -67
- package/lib/context/index.js +7 -5
- package/lib/core/config.js +1 -27
- package/lib/core/exec.js +2 -11
- package/lib/{exempt/index.js → git/exempt-markers.js} +8 -1
- package/lib/git/identity-rewrite.js +1 -1
- package/lib/git/ignore.js +1 -1
- package/lib/git/index.js +1 -1
- package/lib/git/push.js +2 -17
- package/lib/git/repo-index.js +8 -3
- package/lib/git/repos.js +2 -2
- package/lib/git/sensitive.js +1 -1
- package/lib/npm/install.js +1 -1
- package/lib/npm/publish.js +20 -5
- package/lib/npm/registry.js +2 -2
- package/lib/plugin/auto-push.js +5 -8
- package/lib/preprocess/providers.js +195 -0
- package/lib/self/index.js +1 -1
- package/lib/skip-dirs.js +14 -55
- package/package.json +31 -42
- package/skills/dev/dsh-git-push.md +9 -9
- package/skills/guide/guide-commit-push.md +11 -13
- package/skills/workflow/README.md +0 -1
- package/skills/workflow/task-completion-report.md +2 -2
- package/.auditignore +0 -30
- package/.gitignore +0 -43
- package/cli-audit.mjs +0 -141
- package/lib/BUGFIX-NOTES-2026-09-14.md +0 -278
- 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/schema-audit.js +0 -42
- 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/lib/user-requirements.json +0 -15
- 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/build-client.mjs +0 -131
- package/scripts/bump-version.mjs +0 -178
- package/scripts/check-js-scope.mjs +0 -87
- package/scripts/check.mjs +0 -203
- package/scripts/clean-date-comments.py +0 -102
- package/scripts/cpu-sample.mjs +0 -188
- package/scripts/doc-drift.mjs +0 -200
- package/scripts/doc-func.mjs +0 -212
- package/scripts/doc-tree.mjs +0 -458
- package/scripts/doc-version.mjs +0 -149
- 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/local-registry.mjs +0 -37
- 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/scan-version.mjs +0 -125
- package/scripts/symbol-index.mjs +0 -85
- package/scripts/verify-prestep.mjs +0 -100
- package/scripts/version-source.mjs +0 -173
- 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/{audit-defaults.js → git/defaults.js} +0 -0
package/scripts/doc-tree.mjs
DELETED
|
@@ -1,458 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* dsh-git-push — README 目录结构维护脚本(索引自动同步化)
|
|
3
|
-
*
|
|
4
|
-
* 功能(四个子命令):
|
|
5
|
-
* gen —— 用 `git ls-files` 读「所有 git 未忽略文件」,生成目录结构文本
|
|
6
|
-
* (两层折叠:顶层目录全列、子目录只到一层、嵌套用 … 折叠),
|
|
7
|
-
* 每项从 tree-doc.json 取一句话介绍;映射缺失的路径标(待注释)。
|
|
8
|
-
* check —— 解析 README 标记块(<!-- dshgp-tree:start/end -->)内现有树,
|
|
9
|
-
* 与真实文件树对比,报告漂移(新增/删除/改注释),**不改文件**。
|
|
10
|
-
* apply —— 用新生成的树覆盖 README 标记块内容(显式执行才写盘)。
|
|
11
|
-
* sync —— **索引自动同步**:对齐 tree-doc.json 的键集合与真实
|
|
12
|
-
* 文件集——新增文件自动补键(描述=(待注释),等人/AI 补一句介绍);
|
|
13
|
-
* 删除文件自动删键(描述连带删除)。不再需要手动增删键,只补描述。
|
|
14
|
-
*
|
|
15
|
-
* 注释映射:<项目根>/tree-doc.json —— { "路径": "一句话介绍", ... }
|
|
16
|
-
* 键集合(哪些文件被索引)= 脚本自动维护(sync/gen --write);
|
|
17
|
-
* 值(一句话介绍)= 人/AI 手动补:新增文件键值为(待注释),补描述后 git 提交。
|
|
18
|
-
*
|
|
19
|
-
* 用法:
|
|
20
|
-
* node scripts/tree-doc.mjs sync # 索引自动同步(增删键),打印变更统计
|
|
21
|
-
* node scripts/tree-doc.mjs gen # 生成树文本(stdout)
|
|
22
|
-
* node scripts/tree-doc.mjs gen --write # 索引同步 + 补(待注释)后写 tree-doc.json
|
|
23
|
-
* node scripts/tree-doc.mjs gen --all --write # 强制全量追加(等价 sync,显式语义)
|
|
24
|
-
* node scripts/tree-doc.mjs check [--readme README.md] # 检查漂移
|
|
25
|
-
* node scripts/tree-doc.mjs apply [--readme README.md] # 覆盖 README 标记块
|
|
26
|
-
*/
|
|
27
|
-
import { execFileSync } from 'node:child_process';
|
|
28
|
-
import { readFileSync, writeFileSync, existsSync, statSync, readdirSync } from 'node:fs';
|
|
29
|
-
import { join, dirname, resolve, basename } from 'node:path';
|
|
30
|
-
import { fileURLToPath } from 'node:url';
|
|
31
|
-
|
|
32
|
-
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
33
|
-
const MAPPING_FILE = join(ROOT, 'tree-doc.json');
|
|
34
|
-
const MARK_START = '<!-- dshgp-tree:start -->';
|
|
35
|
-
const MARK_END = '<!-- dshgp-tree:end -->';
|
|
36
|
-
const DEFAULT_README = join(ROOT, 'README.md');
|
|
37
|
-
/** 树标记块(宿主 md 识别用)。 */
|
|
38
|
-
|
|
39
|
-
/**
|
|
40
|
-
* 自动探测「目录树宿主 md」(分体式文档支持):
|
|
41
|
-
* · `--readme` 显式指定 → 直接用(向后兼容)。
|
|
42
|
-
* · 缺省:优先 README.md;README 无标记块时,扫描根下全部 .md
|
|
43
|
-
* (docs/ 优先),找第一个含 dshgp-tree 标记块的文件作为宿主——
|
|
44
|
-
* 即「版本/文件树/函数列表等文档放 docs/、README 只引用」格局下,
|
|
45
|
-
* tree-doc 自动写到 docs/ 里真正承载树的那个 md,不再死认 README.md。
|
|
46
|
-
* · 都无标记块 → 回退 README.md(apply 仍会报「无标记块」提示先插标记)。
|
|
47
|
-
* @param {string} root 项目根
|
|
48
|
-
* @param {string} [explicit] --readme 显式路径(空=自动探测)
|
|
49
|
-
* @returns {string} 宿主 md 绝对路径
|
|
50
|
-
*/
|
|
51
|
-
/** 收集根下全部 .md(排除 .git/node_modules/.dsh 等),含 docs/ 子目录,深度 ≤4。 */
|
|
52
|
-
function collectMdFiles(root) {
|
|
53
|
-
const SKIP_DIRS = new Set(['.git', '.dsh', 'node_modules', 'dist', 'build', '.trash']);
|
|
54
|
-
const out = [];
|
|
55
|
-
const walk = (dir, depth) => {
|
|
56
|
-
if (depth > 4) return;
|
|
57
|
-
let entries = [];
|
|
58
|
-
try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
|
|
59
|
-
for (const e of entries) {
|
|
60
|
-
if (e.isDirectory() && SKIP_DIRS.has(e.name)) continue;
|
|
61
|
-
const full = join(dir, e.name);
|
|
62
|
-
if (e.isDirectory()) walk(full, depth + 1);
|
|
63
|
-
else if (e.name.endsWith('.md')) out.push(full);
|
|
64
|
-
}
|
|
65
|
-
};
|
|
66
|
-
walk(root, 0);
|
|
67
|
-
return out;
|
|
68
|
-
}
|
|
69
|
-
|
|
70
|
-
/**
|
|
71
|
-
* 探测含指定标记块的「文档宿主 md」(公共函数,tree-doc/版本表/函数列表三类文档复用)。
|
|
72
|
-
* 优先 README.md;README 无该标记块时,扫描根下全部 .md 找第一个含该标记块的文件。
|
|
73
|
-
* 标记块形如 `<!-- <marker>:start --> … <!-- <marker>:end -->`(marker 如 'dshgp-tree')。
|
|
74
|
-
* @param {string} root 项目根
|
|
75
|
-
* @param {string} marker 标记块名(缺省 dshgp-tree)
|
|
76
|
-
* @returns {string} 宿主 md 绝对路径(找不到含块 md 时回退 README.md)
|
|
77
|
-
*/
|
|
78
|
-
export function findMarkedHostMd(root, marker = 'dshgp-tree') {
|
|
79
|
-
const readme = join(root, 'README.md');
|
|
80
|
-
try {
|
|
81
|
-
if (existsSync(readme) && findBlock(readFileSync(readme, 'utf8'), marker)) return readme;
|
|
82
|
-
} catch { /* 不可读则继续探测 */ }
|
|
83
|
-
for (const f of collectMdFiles(root)) {
|
|
84
|
-
try { if (findBlock(readFileSync(f, 'utf8'), marker)) return f; } catch { /* 忽略坏文件 */ }
|
|
85
|
-
}
|
|
86
|
-
return readme;
|
|
87
|
-
}
|
|
88
|
-
|
|
89
|
-
/** 解析「树宿主 md」——README 不再写死为唯一宿主:自动探测含 dshgp-tree 标记块的 md(分体式文档下宿主可随文档拆分迁移,脚本零改动)。 */
|
|
90
|
-
export function resolveTargetMd(root, explicit = '', marker = 'dshgp-tree') {
|
|
91
|
-
if (explicit) return explicit;
|
|
92
|
-
return findMarkedHostMd(root, marker);
|
|
93
|
-
}
|
|
94
|
-
const TOP_DIRS = [
|
|
95
|
-
'lib', 'scripts', 'assets', 'test', 'docs', 'skills',
|
|
96
|
-
'cli.mjs', 'package.json', 'README.md', 'cordis.patch.yml',
|
|
97
|
-
];
|
|
98
|
-
|
|
99
|
-
/* ───────────────────────── git 未忽略文件清单 ───────────────────────── */
|
|
100
|
-
|
|
101
|
-
function gitLsFiles(root = ROOT) {
|
|
102
|
-
try {
|
|
103
|
-
// 已跟踪 + 未跟踪但未忽略(新文件/待提交都算「未忽略文件」,README 目录树应含它们)
|
|
104
|
-
const out = execFileSync('git', ['-c', 'core.quotepath=false', '-C', root, 'ls-files', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
|
|
105
|
-
return out.split('\n').map((l) => l.trim()).filter(Boolean).filter((p) => {
|
|
106
|
-
// 缺陷修复:--cached 会把「已跟踪但工作区已删」的文件也列出(应只取真实存在的文件)
|
|
107
|
-
// (如 mv 进 .trash 的旧文件仍留在索引),导致 check 误报「真实存在但未列」。
|
|
108
|
-
// 目录树描述的是工作区现状,只保留工作区实际存在的文件。
|
|
109
|
-
try { return statSync(join(root, p)).isFile(); } catch { return false; }
|
|
110
|
-
});
|
|
111
|
-
} catch {
|
|
112
|
-
return [];
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
|
|
116
|
-
/* ───────────────────────── 注释映射读写 ───────────────────────── */
|
|
117
|
-
|
|
118
|
-
function loadMapping(root = ROOT) {
|
|
119
|
-
const mappingFile = join(root, 'tree-doc.json');
|
|
120
|
-
if (!existsSync(mappingFile)) return {};
|
|
121
|
-
try { return JSON.parse(readFileSync(mappingFile, 'utf8')); } catch { return {}; }
|
|
122
|
-
}
|
|
123
|
-
|
|
124
|
-
function writeMapping(map, root = ROOT) {
|
|
125
|
-
writeFileSync(join(root, 'tree-doc.json'), JSON.stringify(map, null, 2) + '\n', 'utf8');
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
/**
|
|
129
|
-
* 工作区未提交变动文件:git status --porcelain → {path: {status, mtime, note}}。
|
|
130
|
-
* M/A/D + 文件 mtime——**面向开发者/AI 的元数据**:提示「该文件变动了,tree-doc 注释可能需更新」。
|
|
131
|
-
* 与 tree-doc.json 的 `_meta.worktree` 配合;apply 到 README 只同步原描述,不含本信息。
|
|
132
|
-
* @returns {Object<string, {status: string, mtime: string, note: string}>}
|
|
133
|
-
*/
|
|
134
|
-
function gitWorktreeChanges(root = ROOT) {
|
|
135
|
-
try {
|
|
136
|
-
const out = execFileSync(
|
|
137
|
-
'git', ['-c', 'core.quotepath=false', '-C', root, 'status', '--porcelain'],
|
|
138
|
-
{ encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 },
|
|
139
|
-
);
|
|
140
|
-
const res = {};
|
|
141
|
-
for (const raw of out.split('\n')) {
|
|
142
|
-
if (!raw.trim()) continue;
|
|
143
|
-
// status --porcelain:前 2 字符 = 状态两列(index/worktree),第 3 字符 = 空格。
|
|
144
|
-
// 不能 trim 整行再 slice(trim 掉前导空格会错位,实测路径首字符被吃)。
|
|
145
|
-
const cell = raw.slice(0, 2);
|
|
146
|
-
const code = cell === '??' ? 'A' : (cell[0] !== ' ' ? cell[0] : (cell[1] !== ' ' ? cell[1] : '')); // ?? 未跟踪=新增
|
|
147
|
-
const path = raw.slice(3).replace(/^"|"$/g, '').trim();
|
|
148
|
-
if (!path || path === 'tree-doc.json') continue; // 排除映射文件自身
|
|
149
|
-
if (!/^[MAD]$/.test(code)) continue; // 只记 M/A/D(R/C/忽略项不算「需更新注释」的变动)
|
|
150
|
-
let mtime = '';
|
|
151
|
-
try { mtime = statSync(join(root, path)).mtime.toISOString(); } catch { /* 已删文件拿不到 mtime */ }
|
|
152
|
-
res[path] = { status: code, mtime, note: '注释可能需更新' };
|
|
153
|
-
}
|
|
154
|
-
return res;
|
|
155
|
-
} catch { return {}; }
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
/**
|
|
159
|
-
* 索引自动同步:对齐 tree-doc.json 键集合与真实文件集。
|
|
160
|
-
* - 新增文件(git 未忽略、工作区存在)不在索引 → 自动补键,值=(待注释),等人补描述
|
|
161
|
-
* - 索引里有但文件已删 → 自动删键(描述连带删除),不再产生孤儿
|
|
162
|
-
* - 目录键(目录级注释合法)自动补齐:真实文件的所有父目录(无尾斜杠,与现有键一致)
|
|
163
|
-
* @param {{write?: boolean, files?: string[], map?: object}} [opts] 测试可注入
|
|
164
|
-
* @returns {{added: string[], removed: string[], map: object}}
|
|
165
|
-
*/
|
|
166
|
-
export function syncIndex({ write = true, files = gitLsFiles(), map = loadMapping(), root = ROOT } = {}) {
|
|
167
|
-
const added = [];
|
|
168
|
-
const removed = [];
|
|
169
|
-
const next = { ...map };
|
|
170
|
-
// 真实存在路径:文件 + 父目录链(目录键无尾斜杠,与 tree-doc.json 现有键一致)
|
|
171
|
-
const realFiles = new Set(files);
|
|
172
|
-
const realDirs = new Set();
|
|
173
|
-
for (const f of files) {
|
|
174
|
-
let dir = f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : null;
|
|
175
|
-
while (dir) {
|
|
176
|
-
realDirs.add(dir);
|
|
177
|
-
const i = dir.lastIndexOf('/');
|
|
178
|
-
dir = i === -1 ? null : dir.slice(0, i);
|
|
179
|
-
}
|
|
180
|
-
}
|
|
181
|
-
// 删除孤儿键(文件或目录已不存在;`_meta` 元数据键保留)
|
|
182
|
-
for (const k of Object.keys(next)) {
|
|
183
|
-
if (k === '_meta') continue;
|
|
184
|
-
if (realFiles.has(k) || realDirs.has(k)) continue;
|
|
185
|
-
removed.push(k);
|
|
186
|
-
delete next[k];
|
|
187
|
-
}
|
|
188
|
-
// 补新增键(文件 + 目录),保持插入顺序稳定(先目录后文件:树父在前)
|
|
189
|
-
// 逐个 add 而不是 new Set([...realDirs, ...realFiles]):避免为去重多复制两个数组一遍
|
|
190
|
-
// (性能规则 performance/memory-bomb「展开多个大数组会一次性创建新数组」;插入顺序不变)
|
|
191
|
-
const want = new Set(realDirs);
|
|
192
|
-
for (const f of realFiles) want.add(f);
|
|
193
|
-
for (const p of want) {
|
|
194
|
-
if (p in next) continue;
|
|
195
|
-
next[p] = '(待注释)';
|
|
196
|
-
added.push(p);
|
|
197
|
-
}
|
|
198
|
-
// 工作区变动文件记录进 `_meta.worktree`(mtime + 状态)——面向开发者/AI 的
|
|
199
|
-
// 提示「注释可能需更新」;apply 到 README 只同步原描述(buildTreeText 只查 map[path]),
|
|
200
|
-
// `_meta` 不进 README。工作区干净时清空该段(避免陈旧提示)。
|
|
201
|
-
const wt = gitWorktreeChanges(root);
|
|
202
|
-
const wtKeys = Object.keys(wt);
|
|
203
|
-
const metaChanged = wtKeys.length
|
|
204
|
-
? JSON.stringify(next._meta?.worktree || null) !== JSON.stringify(wt)
|
|
205
|
-
: Boolean(next._meta?.worktree);
|
|
206
|
-
if (wtKeys.length) next._meta = { ...(next._meta || {}), worktree: wt };
|
|
207
|
-
else if (next._meta?.worktree) delete next._meta.worktree;
|
|
208
|
-
if (next._meta && Object.keys(next._meta).length === 0) delete next._meta;
|
|
209
|
-
if (write && (added.length || removed.length || metaChanged)) writeMapping(next, root);
|
|
210
|
-
return { added, removed, map: next, worktreeChanges: wt };
|
|
211
|
-
}
|
|
212
|
-
|
|
213
|
-
/* ───────────────────────── 两层树构建 ───────────────────────── */
|
|
214
|
-
|
|
215
|
-
/** 顶层归类:返回 { groups: [{name, entries:[路径]}], rootFiles: [路径] } */
|
|
216
|
-
function buildGroups(files) {
|
|
217
|
-
const groups = new Map(); // 顶层目录名 → 其下文件路径列表
|
|
218
|
-
const rootFiles = [];
|
|
219
|
-
const known = new Set(TOP_DIRS);
|
|
220
|
-
for (const f of files) {
|
|
221
|
-
const top = f.split('/')[0];
|
|
222
|
-
if (!f.includes('/')) rootFiles.push(f); // 根级文件
|
|
223
|
-
else {
|
|
224
|
-
if (!groups.has(top)) groups.set(top, []);
|
|
225
|
-
groups.get(top).push(f);
|
|
226
|
-
}
|
|
227
|
-
}
|
|
228
|
-
// 未在 TOP_DIRS 的顶层目录也归组(放后面)
|
|
229
|
-
const groupNames = [...groups.keys()];
|
|
230
|
-
const order = [...TOP_DIRS.filter((k) => groups.has(k)), ...groupNames.filter((n) => !TOP_DIRS.includes(n))];
|
|
231
|
-
return { groups, groupNames: order, rootFiles: [...new Set(rootFiles)] };
|
|
232
|
-
}
|
|
233
|
-
|
|
234
|
-
/** 目录组 → 两层折叠文本行(子目录只到一层,更深用 …) */
|
|
235
|
-
function groupLines(name, paths, map, prefix = '') {
|
|
236
|
-
const lines = [];
|
|
237
|
-
// 该组下第一层:直接文件 vs 子目录
|
|
238
|
-
const direct = [];
|
|
239
|
-
const subdirs = new Map(); // 子目录名 → 其下文件
|
|
240
|
-
for (const p of paths) {
|
|
241
|
-
const rest = p.slice(name.length + 1); // 去掉顶层
|
|
242
|
-
if (!rest.includes('/')) direct.push(p);
|
|
243
|
-
else {
|
|
244
|
-
const sub = rest.split('/')[0];
|
|
245
|
-
if (!subdirs.has(sub)) subdirs.set(sub, []);
|
|
246
|
-
subdirs.get(sub).push(p);
|
|
247
|
-
}
|
|
248
|
-
}
|
|
249
|
-
const note = (p) => (map[p] ? map[p] : '(待注释)');
|
|
250
|
-
for (const entry of direct.sort()) lines.push(`│ ├── ${basename(entry)} — ${note(entry)}`);
|
|
251
|
-
for (const [sub, items] of [...subdirs.entries()].sort()) {
|
|
252
|
-
const subPath = `${name}/${sub}`;
|
|
253
|
-
// 第二层直接文件;更深折叠
|
|
254
|
-
const second = items.map((p) => p.slice(subPath.length + 1)).filter((r) => !r.includes('/')).sort();
|
|
255
|
-
const deeper = items.filter((p) => p.slice(subPath.length + 1).includes('/')).length;
|
|
256
|
-
lines.push(`│ ├── ${sub}/ — ${map[subPath] || (second.length ? '' : '(待注释)')}`);
|
|
257
|
-
for (const s of second) lines.push(`│ │ ├── ${s} — ${note(`${subPath}/${s}`)}`);
|
|
258
|
-
if (deeper) lines.push(`│ │ └── …(${deeper} 个更深文件)`);
|
|
259
|
-
}
|
|
260
|
-
return lines;
|
|
261
|
-
}
|
|
262
|
-
|
|
263
|
-
/** 生成完整树文本(顶层分组 + 根文件,两层折叠) */
|
|
264
|
-
export function buildTreeText(files = gitLsFiles(), map = loadMapping(), rootLabel = basename(ROOT)) {
|
|
265
|
-
const { groups, groupNames, rootFiles } = buildGroups(files);
|
|
266
|
-
const out = ['```text', rootLabel + '/'];
|
|
267
|
-
for (const groupName of groupNames) {
|
|
268
|
-
out.push(`├── ${groupName}/ — ${map[groupName] || '(待注释)'}`);
|
|
269
|
-
out.push(...groupLines(groupName, groups.get(groupName), map));
|
|
270
|
-
}
|
|
271
|
-
for (const rf of [...rootFiles].sort()) {
|
|
272
|
-
out.push(`├── ${rf} — ${map[rf] || '(待注释)'}`);
|
|
273
|
-
}
|
|
274
|
-
out.push('```');
|
|
275
|
-
return out.join('\n');
|
|
276
|
-
}
|
|
277
|
-
|
|
278
|
-
/* ───────────────────────── README 标记块读写 ───────────────────────── */
|
|
279
|
-
|
|
280
|
-
/** 找文本内的标记块(marker 如 'dshgp-tree';块 = <!-- <marker>:start --> … <!-- <marker>:end -->)。 */
|
|
281
|
-
function findBlock(text, marker = 'dshgp-tree') {
|
|
282
|
-
const sMark = `<!-- ${marker}:start -->`;
|
|
283
|
-
const eMark = `<!-- ${marker}:end -->`;
|
|
284
|
-
const s = text.indexOf(sMark);
|
|
285
|
-
const e = text.indexOf(eMark);
|
|
286
|
-
if (s === -1 || e === -1 || e <= s) return null;
|
|
287
|
-
return { start: s, end: e, content: text.slice(s + sMark.length, e) };
|
|
288
|
-
}
|
|
289
|
-
|
|
290
|
-
function readReadme(path) {
|
|
291
|
-
if (!existsSync(path)) throw new Error(`README 不存在: ${path}`);
|
|
292
|
-
return readFileSync(path, 'utf8');
|
|
293
|
-
}
|
|
294
|
-
|
|
295
|
-
function applyBlock(text, newTree) {
|
|
296
|
-
const block = findBlock(text);
|
|
297
|
-
if (!block) throw new Error('README 未找到标记块(<!-- dshgp-tree:start --> … <!-- dshgp-tree:end -->),先插入标记再 apply');
|
|
298
|
-
return text.slice(0, block.start) + MARK_START + '\n' + newTree + '\n' + MARK_END + text.slice(block.end + MARK_END.length);
|
|
299
|
-
}
|
|
300
|
-
|
|
301
|
-
/* ───────────────────────── check:漂移对比 ───────────────────────── */
|
|
302
|
-
|
|
303
|
-
export function checkDrift({ readmePath = '', root = ROOT } = {}) {
|
|
304
|
-
// 树宿主可迁移(README 拆出后落到 docs/ 下带标记块的 md)⇒ 与 apply 同用 resolveTargetMd
|
|
305
|
-
// 自动探测,而不是写死 README。显式传 readmePath 时行为不变。
|
|
306
|
-
const text = readReadme(resolveTargetMd(root, readmePath));
|
|
307
|
-
const block = findBlock(text);
|
|
308
|
-
const real = buildTreeText(gitLsFiles(root), loadMapping(root), basename(root));
|
|
309
|
-
const map = loadMapping(root);
|
|
310
|
-
// 真实树内已解析条目(路径集合)
|
|
311
|
-
const realPaths = new Set(gitLsFiles(root));
|
|
312
|
-
const issues = [];
|
|
313
|
-
if (!block) {
|
|
314
|
-
issues.push({ type: 'no-block', msg: `${basename(readmePath)} 没有目录结构标记块(${MARK_START} … ${MARK_END});可 apply 前先插入标记,或把树写到带标记的 docs/ md(自动探测)` });
|
|
315
|
-
return { ok: false, drift: true, issues, realTree: real };
|
|
316
|
-
}
|
|
317
|
-
// 现有块内容 → 提取完整相对路径(按缩进深度拼层级),目录带尾斜杠
|
|
318
|
-
const inBlock = block.content;
|
|
319
|
-
const seen = new Set();
|
|
320
|
-
const foldedDirs = []; // 折叠点目录(… N 个更深文件 → 该目录下更深文件不逐项核对)
|
|
321
|
-
let stack = [];
|
|
322
|
-
for (const line of inBlock.split('\n')) {
|
|
323
|
-
// 缩进深度 = 前缀 `│ ` 的个数(顶层=0)
|
|
324
|
-
const depth = (line.match(/│ /g) || []).length;
|
|
325
|
-
const lineText = line.replace(/^(\s*)(?:│ )*(?:├──|└──)\s*/, '').trim();
|
|
326
|
-
if (!lineText || lineText.startsWith('```')) continue; // 跳过代码围栏行
|
|
327
|
-
if (lineText.startsWith('…')) {
|
|
328
|
-
// 折叠行:当前目录链即折叠点(其下更深文件除外)
|
|
329
|
-
if (stack.length) foldedDirs.push(stack.join('/') + '/');
|
|
330
|
-
continue;
|
|
331
|
-
}
|
|
332
|
-
// 按「—」切出名字段(trim 后破折号后无空格,split(' — ') 会失效)
|
|
333
|
-
const name = lineText.split('—')[0].trim();
|
|
334
|
-
// 修:树根节点豁免原硬编码本插件名(dsh-git-push)——扫描其它仓库(如
|
|
335
|
-
// dsh-theme-mediascape)时根节点 <repoName>/ 被误判 stale。改为动态豁免当前 git 根目录名。
|
|
336
|
-
const repoRoot = basename(root);
|
|
337
|
-
if (!name || name === repoRoot || name === repoRoot + '/') continue;
|
|
338
|
-
stack = stack.slice(0, depth); // 回退到当前深度
|
|
339
|
-
if (name.endsWith('/')) {
|
|
340
|
-
const dir = name.slice(0, -1);
|
|
341
|
-
seen.add([...stack, dir].join('/') + '/');
|
|
342
|
-
stack = [...stack, dir];
|
|
343
|
-
} else {
|
|
344
|
-
seen.add([...stack, name].join('/'));
|
|
345
|
-
}
|
|
346
|
-
}
|
|
347
|
-
// 真实路径集合(git 未忽略文件 + 真实目录)
|
|
348
|
-
const realSet = new Set();
|
|
349
|
-
for (const p of realPaths) realSet.add(p);
|
|
350
|
-
const isRealDir = (p) => { try { return statSync(join(root, p.replace(/\/$/, ''))).isDirectory(); } catch { return false; } };
|
|
351
|
-
// 工具自产生成物不追漂移——tree-doc/functions 自产(README 树与索引的
|
|
352
|
-
// 增删由工具维护,不属手写树内容):docs/函数/*(apply 生成/删除常态)、
|
|
353
|
-
// functions-index.json(analyze 产物)。_meta 见 orphan 判定。
|
|
354
|
-
const isToolGenerated = (p) => p === 'functions-index.json' || p === '_meta'
|
|
355
|
-
|| p.startsWith('docs/函数/') || p.includes('_archived/');
|
|
356
|
-
// missing:真实文件不在树上(被折叠的设计除外;工具生成物豁免)
|
|
357
|
-
const missing = [];
|
|
358
|
-
for (const p of realPaths) {
|
|
359
|
-
const folded = foldedDirs.some((d) => p.startsWith(d));
|
|
360
|
-
if (!folded && !seen.has(p) && !isRealDir(p) && !isToolGenerated(p)) missing.push(p);
|
|
361
|
-
}
|
|
362
|
-
// stale:树上列出但真实不存在(文件或目录;工具生成物豁免)
|
|
363
|
-
const stale = [];
|
|
364
|
-
for (const s of seen) {
|
|
365
|
-
if (isToolGenerated(s)) continue;
|
|
366
|
-
if (s.endsWith('/')) { if (!isRealDir(s)) stale.push(s); }
|
|
367
|
-
else if (!realSet.has(s)) stale.push(s);
|
|
368
|
-
}
|
|
369
|
-
// 注释映射孤儿:路径既不是 git 文件,也不是真实目录(目录级注释合法);`_meta`/生成物键跳过
|
|
370
|
-
const orphans = [];
|
|
371
|
-
for (const p of Object.keys(map)) {
|
|
372
|
-
if (isToolGenerated(p)) continue; // _meta 元数据 + docs/函数/ 等工具产物不算孤儿
|
|
373
|
-
const full = join(root, p);
|
|
374
|
-
let realDir = false;
|
|
375
|
-
try { realDir = statSync(full).isDirectory(); } catch { /* 路径不存在:不算真实目录 */ }
|
|
376
|
-
if (!realSet.has(p) && !realDir) orphans.push(p);
|
|
377
|
-
}
|
|
378
|
-
const drift = missing.length > 0 || stale.length > 0 || orphans.length > 0;
|
|
379
|
-
if (missing.length) issues.push({ type: 'missing', msg: `真实存在但 README 未列(新增未更新): ${missing.slice(0, 12).join(', ')}${missing.length > 12 ? `…(+${missing.length - 12})` : ''}` });
|
|
380
|
-
if (stale.length) issues.push({ type: 'stale', msg: `README 列出但真实不存在(已删除): ${stale.join(', ')}` });
|
|
381
|
-
if (orphans.length) issues.push({ type: 'orphan', msg: `tree-doc.json 映射了不存在的路径(运行 tree-doc.mjs sync 自动清理): ${orphans.slice(0, 8).join(', ')}${orphans.length > 8 ? `…(+${orphans.length - 8})` : ''}` });
|
|
382
|
-
return { ok: !drift, drift, issues, realTree: real, worktreeChanges: gitWorktreeChanges(root) };
|
|
383
|
-
}
|
|
384
|
-
|
|
385
|
-
/* ───────────────────────── CLI ───────────────────────── */
|
|
386
|
-
// 仅直接运行时执行(测试 import 本文件不应触发 CLI)
|
|
387
|
-
const isMain = process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1]);
|
|
388
|
-
|
|
389
|
-
if (isMain) {
|
|
390
|
-
const args = process.argv.slice(2);
|
|
391
|
-
const cmd = args[0];
|
|
392
|
-
// `--root <路径>` 支持外调其他项目——其他仓库可直接用本脚本维护自己的
|
|
393
|
-
// README 目录树(`node <dsh-git-push>/scripts/tree-doc.mjs check --root <其他项目根>`)。
|
|
394
|
-
// 缺省 = 自身项目(向后兼容);显式 `--readme` 优先于 root 推导的 README 路径。
|
|
395
|
-
const rootIdx = args.indexOf('--root');
|
|
396
|
-
const rootArg = rootIdx !== -1 && args[rootIdx + 1] ? resolve(args[rootIdx + 1]) : ROOT;
|
|
397
|
-
// README 不再写死——自动探测宿主 md(README 无标记块时找 docs/ 里带标记块的)
|
|
398
|
-
const readmeIdx = args.indexOf('--readme');
|
|
399
|
-
const readmeExplicit = readmeIdx !== -1 && args[readmeIdx + 1] ? resolve(args[readmeIdx + 1]) : '';
|
|
400
|
-
const readmePath = readmeExplicit || resolveTargetMd(rootArg);
|
|
401
|
-
const forceAll = args.includes('--all');
|
|
402
|
-
const filesOf = (r) => gitLsFiles(r);
|
|
403
|
-
const mapOf = (r) => loadMapping(r);
|
|
404
|
-
|
|
405
|
-
switch (cmd) {
|
|
406
|
-
case 'sync': {
|
|
407
|
-
// 索引自动同步:新增补(待注释)、删除自动删键(描述连带删)
|
|
408
|
-
const files = filesOf(rootArg);
|
|
409
|
-
const { added, removed, map } = syncIndex({ write: !args.includes('--dry'), files, map: mapOf(rootArg), root: rootArg });
|
|
410
|
-
const dirs = new Set();
|
|
411
|
-
for (const f of files) {
|
|
412
|
-
let dir = f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : null;
|
|
413
|
-
while (dir) { dirs.add(dir + '/'); const i = dir.lastIndexOf('/'); dir = i === -1 ? null : dir.slice(0, i); }
|
|
414
|
-
}
|
|
415
|
-
const tree = buildTreeText(files, map, basename(rootArg));
|
|
416
|
-
if (added.length) console.log(`✅ 新增索引键 ${added.length} 个(值=(待注释),请补描述):\n ${added.join('\n ')}`);
|
|
417
|
-
if (removed.length) console.log(`🗑 删除索引键 ${removed.length} 个(文件已删,描述连带删除):\n ${removed.join('\n ')}`);
|
|
418
|
-
if (!added.length && !removed.length) console.log('✅ 索引已同步(无新增/删除)');
|
|
419
|
-
if (args.includes('--write-tree')) writeFileSync(readmePath, applyBlock(readReadme(readmePath), tree), 'utf8');
|
|
420
|
-
console.log(`(tree-doc.json 现有 ${Object.keys(map).length} 键;gen 输出见 tree-doc.mjs gen)`);
|
|
421
|
-
break;
|
|
422
|
-
}
|
|
423
|
-
case 'gen': {
|
|
424
|
-
const files = filesOf(rootArg);
|
|
425
|
-
if (args.includes('--write')) {
|
|
426
|
-
// 索引同步 + 补(待注释)(与 sync 同一逻辑——--all 为显式全量语义:显式声明时连已同步键也重写,默认只补缺)
|
|
427
|
-
const { added, removed } = syncIndex({ write: true, files, map: mapOf(rootArg), root: rootArg });
|
|
428
|
-
if (forceAll) console.log('--all:已强制全量追加索引');
|
|
429
|
-
console.log(`tree-doc.json 已同步(新增 ${added.length} / 删除 ${removed.length};${added.length ? '待注释键请补描述' : ''})`);
|
|
430
|
-
} else {
|
|
431
|
-
console.log(buildTreeText(files, mapOf(rootArg), basename(rootArg)));
|
|
432
|
-
}
|
|
433
|
-
break;
|
|
434
|
-
}
|
|
435
|
-
case 'check': {
|
|
436
|
-
const r = checkDrift({ readmePath, root: rootArg });
|
|
437
|
-
if (r.ok) { console.log(`✅ 目录结构与 README 一致(无漂移)${rootArg !== ROOT ? ` @ ${rootArg}` : ''}`); process.exit(0); }
|
|
438
|
-
console.log('❌ 存在漂移:');
|
|
439
|
-
for (const i of r.issues) console.log(' -', i.msg);
|
|
440
|
-
if (r.realTree) console.log('\n═══ 最新树(可用 apply 覆盖)═══\n' + r.realTree);
|
|
441
|
-
process.exit(1);
|
|
442
|
-
}
|
|
443
|
-
case 'apply': {
|
|
444
|
-
// apply 前先同步索引,保证树用最新映射(描述缺失处标(待注释))
|
|
445
|
-
if (args.includes('--sync') || forceAll) syncIndex({ write: true, files: filesOf(rootArg), map: mapOf(rootArg), root: rootArg });
|
|
446
|
-
const tree = buildTreeText(filesOf(rootArg), mapOf(rootArg), basename(rootArg));
|
|
447
|
-
const text = readReadme(readmePath);
|
|
448
|
-
const updated = applyBlock(text, tree);
|
|
449
|
-
writeFileSync(readmePath, updated, 'utf8');
|
|
450
|
-
console.log(`✅ 已覆盖目录结构块: ${readmePath}`);
|
|
451
|
-
if (!readmePath.endsWith('README.md')) console.log(' ℹ️ 宿主为非 README md——确保 README 以链接引用它(分体式文档,见插件 skill「文档组织」节)');
|
|
452
|
-
break;
|
|
453
|
-
}
|
|
454
|
-
default:
|
|
455
|
-
console.log('用法: node scripts/tree-doc.mjs <sync|gen|check|apply> [--root <项目根>] [--readme <路径>] [--write] [--all] [--dry]');
|
|
456
|
-
process.exit(1);
|
|
457
|
-
}
|
|
458
|
-
}
|
package/scripts/doc-version.mjs
DELETED
|
@@ -1,149 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
/**
|
|
3
|
-
* dsh-git-push — 版本列表文档生成器(doc-version:版本表由**文件**权威生成,防手写版本记录漂移)
|
|
4
|
-
* dsh-skip-i18n: 用户可见文案硬编码为产品设计
|
|
5
|
-
*
|
|
6
|
-
* 分体式文档三兄弟之一(doc-tree 文件树 / doc-func 函数列表 / doc-version 版本列表)。
|
|
7
|
-
* 版本表数据源 = `docs/releases.json`(每版一行说明)+ 版本真源文件(package.json 等)
|
|
8
|
-
* + `version-metrics.json`(可选量化记录);**不读 git log**(2026-10-16 改,原因见
|
|
9
|
-
* version-source.mjs 的 buildReadmeVersionTable 注释)。
|
|
10
|
-
* 写入宿主 md(README 有 dshgp-version 标记块用 README,否则 docs/ 带块 md)。
|
|
11
|
-
* 复用 version-source.mjs 的 buildReadmeVersionTable(版本聚合逻辑单一事实源)。
|
|
12
|
-
*
|
|
13
|
-
* 用法:
|
|
14
|
-
* node scripts/doc-version.mjs gen [--root <项目根>] # 打印版本表文本
|
|
15
|
-
* node scripts/doc-version.mjs apply [--root <项目根>] # 写入宿主 md(自动探测)
|
|
16
|
-
* node scripts/doc-version.mjs check [--root <项目根>] # 比对宿主块与最新(漂移报错)
|
|
17
|
-
*/
|
|
18
|
-
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
|
|
19
|
-
import { join, resolve, relative, basename, dirname } from 'node:path';
|
|
20
|
-
import { fileURLToPath } from 'node:url';
|
|
21
|
-
import { findMarkedHostMd } from './doc-tree.mjs';
|
|
22
|
-
import { buildReadmeVersionTable, detectVersionSource, projectVersionOf, readReleases, VERSION_SOURCES } from './version-source.mjs';
|
|
23
|
-
|
|
24
|
-
const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
25
|
-
const MARKER = 'dshgp-version';
|
|
26
|
-
const MARK_START = `<!-- ${MARKER}:start -->`;
|
|
27
|
-
const MARK_END = `<!-- ${MARKER}:end -->`;
|
|
28
|
-
|
|
29
|
-
/**
|
|
30
|
-
* 版本源探测与读取**在 scripts/version-source.mjs**(版本表生成与版本源同源,避免两处各写一份)。
|
|
31
|
-
* 这里只做再导出,保持旧调用方的 import 路径不变。
|
|
32
|
-
*
|
|
33
|
-
* ⚠️ 2026-10-16 起:版本表**不再读 git log**(`detectVersionSource` 不再回退 'git-log')——
|
|
34
|
-
* 表内容由 `docs/releases.json` + 版本真源文件生成,普通提交不再动表、也不再逼人「为门禁升版本」。
|
|
35
|
-
*/
|
|
36
|
-
// 本地再导出(`export … from` 不产生本地绑定 ⇒ 必须先 import 再导出)
|
|
37
|
-
export { VERSION_SOURCES, detectVersionSource, projectVersionOf, readReleases };
|
|
38
|
-
|
|
39
|
-
/** 兼容旧调用:等价于"按项目类型识别后取版本号"。 */
|
|
40
|
-
export function packageVersionOf(root) {
|
|
41
|
-
return projectVersionOf(root, detectVersionSource(root));
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
/** 生成版本列表 markdown(宿主块内容)——**纯文件驱动,不读 git log**。
|
|
45
|
-
* 行内容来自 buildReadmeVersionTable(docs/releases.json + 版本真源 + version-metrics.json)。 */
|
|
46
|
-
export function buildVersionListText(root, _opts = {}) {
|
|
47
|
-
const rows = buildReadmeVersionTable(root);
|
|
48
|
-
const source = detectVersionSource(root) || '(无版本源文件)';
|
|
49
|
-
const pkg = projectVersionOf(root);
|
|
50
|
-
return { text: `## 版本列表\n\n${rows.join('\n')}\n`, rows: rows.length - 2, source, packageVersion: pkg };
|
|
51
|
-
}
|
|
52
|
-
|
|
53
|
-
/** 找宿主 md 内的 dshgp-version 标记块。 */
|
|
54
|
-
function findBlock(text) {
|
|
55
|
-
const s = text.indexOf(MARK_START);
|
|
56
|
-
const e = text.indexOf(MARK_END);
|
|
57
|
-
if (s === -1 || e === -1 || e <= s) return null;
|
|
58
|
-
return { start: s, end: e, content: text.slice(s + MARK_START.length, e) };
|
|
59
|
-
}
|
|
60
|
-
|
|
61
|
-
/** 替换/插入标记块。无块时追加到文件尾。 */
|
|
62
|
-
export function applyVersionBlock(text, newContent) {
|
|
63
|
-
const block = findBlock(text);
|
|
64
|
-
if (block) return text.slice(0, block.start) + MARK_START + '\n' + newContent + '\n' + MARK_END + text.slice(block.end + MARK_END.length);
|
|
65
|
-
return text.replace(/\s*$/, '\n') + `\n${MARK_START}\n${newContent}\n${MARK_END}\n`;
|
|
66
|
-
}
|
|
67
|
-
|
|
68
|
-
/** 比对宿主块与最新版本表。返回 { ok, issues, latest }。 */
|
|
69
|
-
export function checkVersionDrift({ hostPath, root, versionSource = '' } = {}) {
|
|
70
|
-
const { text: latest, source } = buildVersionListText(root, { versionSource });
|
|
71
|
-
const host = existsSync(hostPath) ? readFileSync(hostPath, 'utf8') : '';
|
|
72
|
-
const block = findBlock(host);
|
|
73
|
-
const issues = [];
|
|
74
|
-
if (!block) issues.push({ type: 'no-block', msg: `${basename(hostPath)} 无版本列表标记块(${MARK_START} … ${MARK_END}),先 apply 生成` });
|
|
75
|
-
else if (block.content.trim() !== latest.trim()) issues.push({ type: 'drift', msg: `版本列表与期望内容不一致(来源:${source},运行 doc-version.mjs apply 更新)` });
|
|
76
|
-
return { ok: issues.length === 0, issues, latest, source };
|
|
77
|
-
}
|
|
78
|
-
|
|
79
|
-
/* ─────────── CLI ─────────── */
|
|
80
|
-
|
|
81
|
-
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
82
|
-
const args = process.argv.slice(2);
|
|
83
|
-
const cmd = args[0];
|
|
84
|
-
const rootIdx = args.indexOf('--root');
|
|
85
|
-
const root = rootIdx !== -1 && args[rootIdx + 1] ? resolve(args[rootIdx + 1]) : ROOT;
|
|
86
|
-
// 版本来源可显式指定(package.json | git-log);不传则按项目类型自动识别(有 package.json 即 npm 项目)
|
|
87
|
-
const srcIdx = args.indexOf('--version-source');
|
|
88
|
-
const versionSource = srcIdx !== -1 && args[srcIdx + 1] ? String(args[srcIdx + 1]) : '';
|
|
89
|
-
if (versionSource && versionSource !== 'package.json') {
|
|
90
|
-
console.log(`❌ --version-source 只接受 package.json(版本表已改为文件驱动,不再支持 git-log),收到:${versionSource}`);
|
|
91
|
-
process.exit(1);
|
|
92
|
-
}
|
|
93
|
-
const host = findMarkedHostMd(root, MARKER);
|
|
94
|
-
const out = (msg) => console.log(msg);
|
|
95
|
-
|
|
96
|
-
if (cmd === 'gen') {
|
|
97
|
-
const r = buildVersionListText(root, { versionSource });
|
|
98
|
-
out(r.text);
|
|
99
|
-
out(`\n(${r.rows} 版本行;来源 ${r.source};apply 写入 ${relative(root, host) || 'README.md'})`);
|
|
100
|
-
process.exit(0);
|
|
101
|
-
}
|
|
102
|
-
if (cmd === 'apply') {
|
|
103
|
-
const r = buildVersionListText(root, { versionSource });
|
|
104
|
-
const hostText = existsSync(host) ? readFileSync(host, 'utf8') : '';
|
|
105
|
-
const force = args.includes('--force');
|
|
106
|
-
// ── 预演(dry-run):先看清"将写入几行、首行是什么",再决定落盘 ──
|
|
107
|
-
// 破坏性写入前必须能预演;`gen` 也能看内容,但 dry-run 额外报出目标文件与现有行数对比。
|
|
108
|
-
if (args.includes('--dry-run')) {
|
|
109
|
-
const curB = findBlock(hostText);
|
|
110
|
-
const curN = curB ? (curB.content.match(/^\|\s*\d+\.\d+\.\d+\s*\|/gm) || []).length : 0;
|
|
111
|
-
out(`[dry-run] 目标文件:${relative(root, host) || 'README.md'}`);
|
|
112
|
-
out(`[dry-run] 将写入:${r.rows} 版本行(来源 ${r.source});现有:${curN} 行`);
|
|
113
|
-
out(`[dry-run] 首行预览:${(r.text.split('\n').find((l) => /^\|\s*\d/.test(l)) || '(无数据行)').trim()}`);
|
|
114
|
-
out('[dry-run] 未做任何写入。');
|
|
115
|
-
process.exit(0);
|
|
116
|
-
}
|
|
117
|
-
// ── 安全闸(2026-10-10 真实事故:本工具静默把整张版本表清空)──
|
|
118
|
-
// 0 行的常见原因**不是**"项目真的没有版本",而是 git log 读不到(如本机 dubious ownership,
|
|
119
|
-
// git 直接拒绝该仓库)⇒ 此时必须拒绝写盘,绝不覆盖现有版本表。
|
|
120
|
-
if (!force && !(r.rows > 0)) {
|
|
121
|
-
out(`❌ 拒绝写盘:聚合出 0 条版本行(来源 ${r.source})——现有版本表保持不变,未做任何修改。`);
|
|
122
|
-
out(' 常见原因:git log 读不到该仓库(例如 dubious ownership 被 git 拒绝)。先执行:');
|
|
123
|
-
out(" git config --global --add safe.directory '*'");
|
|
124
|
-
out(' 再用 `node scripts/doc-version.mjs gen` 确认能输出真实版本行(非 0 行)后重试;');
|
|
125
|
-
out(' 确实要写空表时显式加 --force。');
|
|
126
|
-
process.exit(2);
|
|
127
|
-
}
|
|
128
|
-
// ── 骤减保护:新表行数少于现有表行数 ⇒ 疑似聚合来源异常(log 不完整/换源),同样拒绝写盘 ──
|
|
129
|
-
const curBlock = findBlock(hostText);
|
|
130
|
-
const curRows = curBlock ? (curBlock.content.match(/^\|\s*\d+\.\d+\.\d+\s*\|/gm) || []).length : 0;
|
|
131
|
-
if (!force && curRows > 0 && r.rows < curRows) {
|
|
132
|
-
out(`❌ 拒绝写盘:本次聚合 ${r.rows} 行 < 现有 ${curRows} 行(疑似聚合来源异常,如 git log 不完整或换源)。`);
|
|
133
|
-
out(' 现有版本表保持不变;确认要缩减请先备份,再显式加 --force。');
|
|
134
|
-
process.exit(2);
|
|
135
|
-
}
|
|
136
|
-
writeFileSync(host, applyVersionBlock(hostText, r.text), 'utf8');
|
|
137
|
-
out(`✅ 已写入版本列表 → ${relative(root, host) || 'README.md'}(${r.rows} 版本行;来源 ${r.source})`);
|
|
138
|
-
process.exit(0);
|
|
139
|
-
}
|
|
140
|
-
if (cmd === 'check') {
|
|
141
|
-
const r = checkVersionDrift({ hostPath: host, root, versionSource });
|
|
142
|
-
if (r.ok) { out(`✅ 版本列表一致(来源 ${r.source})`); process.exit(0); }
|
|
143
|
-
out('❌ 版本列表存在差异:');
|
|
144
|
-
for (const i of r.issues) out(' - ' + i.msg);
|
|
145
|
-
process.exit(1);
|
|
146
|
-
}
|
|
147
|
-
out('用法: node scripts/doc-version.mjs <gen|apply|check> [--root <项目根>] [--version-source package.json|git-log]');
|
|
148
|
-
process.exit(1);
|
|
149
|
-
}
|