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.
Files changed (278) hide show
  1. package/.auditignore +30 -0
  2. package/.gitignore +39 -0
  3. package/LICENSE +21 -0
  4. package/README.md +1482 -2
  5. package/cli.mjs +360 -0
  6. package/cordis.patch.yml +14 -0
  7. package/lib/ARCHITECTURE.md +34 -0
  8. package/lib/BUGFIX-NOTES-2026-09-14.md +278 -0
  9. package/lib/app/apply.js +275 -0
  10. package/lib/app/audit-api.js +158 -0
  11. package/lib/app/command-registry.js +262 -0
  12. package/lib/app/constants.js +16 -0
  13. package/lib/app/handlers/account.js +166 -0
  14. package/lib/app/handlers/clone.js +168 -0
  15. package/lib/app/handlers/http-constants.js +9 -0
  16. package/lib/app/handlers/identity-rewrite.js +94 -0
  17. package/lib/app/handlers/meta.js +175 -0
  18. package/lib/app/handlers/npm.js +169 -0
  19. package/lib/app/handlers/repo-actions.js +143 -0
  20. package/lib/app/handlers/repos.js +231 -0
  21. package/lib/app/handlers/settings.js +62 -0
  22. package/lib/app/host-doc-checks.js +25 -0
  23. package/lib/app/http-handlers.js +131 -0
  24. package/lib/app/index.js +30 -0
  25. package/lib/app/inject-text.js +191 -0
  26. package/lib/app/scan-root.js +23 -0
  27. package/lib/app/schema.js +150 -0
  28. package/lib/app/settings-bridge.js +167 -0
  29. package/lib/app/slash-commands.js +395 -0
  30. package/lib/app/slot-stats.js +35 -0
  31. package/lib/app/tool-call.js +662 -0
  32. package/lib/app/tools.js +40 -0
  33. package/lib/ast/brace.js +105 -0
  34. package/lib/ast/callgraph.js +135 -0
  35. package/lib/ast/code-lines.js +114 -0
  36. package/lib/ast/consts.js +12 -0
  37. package/lib/ast/control-flow.js +461 -0
  38. package/lib/ast/credential.js +199 -0
  39. package/lib/ast/dataflow.js +274 -0
  40. package/lib/ast/dup-code.js +165 -0
  41. package/lib/ast/index.js +36 -0
  42. package/lib/ast/io-risk-const.js +95 -0
  43. package/lib/ast/io-risk-fn.js +208 -0
  44. package/lib/ast/io-risk-loop.js +308 -0
  45. package/lib/ast/io-risk.js +314 -0
  46. package/lib/ast/lang.js +156 -0
  47. package/lib/ast/line-count.js +52 -0
  48. package/lib/ast/magic-number.js +272 -0
  49. package/lib/ast/naming.js +284 -0
  50. package/lib/ast/perf.js +472 -0
  51. package/lib/ast/scope.js +241 -0
  52. package/lib/ast/shell.js +131 -0
  53. package/lib/ast/size.js +378 -0
  54. package/lib/ast/symbol-index.js +399 -0
  55. package/lib/ast/tokenizer.js +341 -0
  56. package/lib/audit/analysis-coverage.js +98 -0
  57. package/lib/audit/audit-file.js +182 -0
  58. package/lib/audit/checks.js +17 -0
  59. package/lib/audit/client-entry.js +93 -0
  60. package/lib/audit/collector.js +477 -0
  61. package/lib/audit/ext-runner.js +80 -0
  62. package/lib/audit/file-context.js +138 -0
  63. package/lib/audit/finding.js +50 -0
  64. package/lib/audit/gitignore-match.js +113 -0
  65. package/lib/audit/glob.js +63 -0
  66. package/lib/audit/history-report.js +100 -0
  67. package/lib/audit/history.js +126 -0
  68. package/lib/audit/ignore-blind.js +101 -0
  69. package/lib/audit/index.js +33 -0
  70. package/lib/audit/orchestrate.js +476 -0
  71. package/lib/audit/public.js +24 -0
  72. package/lib/audit/repo-level.js +30 -0
  73. package/lib/audit/report-yaml.js +86 -0
  74. package/lib/audit/slot.js +65 -0
  75. package/lib/audit-defaults.js +18 -0
  76. package/lib/audit-rules/audit-rules-comment.yml +247 -0
  77. package/lib/audit-rules/audit-rules-cpp.yml +22 -0
  78. package/lib/audit-rules/audit-rules-docs.yml +32 -0
  79. package/lib/audit-rules/audit-rules-dsh.yml +162 -0
  80. package/lib/audit-rules/audit-rules-filehealth.yml +42 -0
  81. package/lib/audit-rules/audit-rules-folder.yml +99 -0
  82. package/lib/audit-rules/audit-rules-frontend.yml +335 -0
  83. package/lib/audit-rules/audit-rules-go.yml +22 -0
  84. package/lib/audit-rules/audit-rules-i18n.yml +45 -0
  85. package/lib/audit-rules/audit-rules-java.yml +105 -0
  86. package/lib/audit-rules/audit-rules-nodejs.yml +647 -0
  87. package/lib/audit-rules/audit-rules-npm.yml +187 -0
  88. package/lib/audit-rules/audit-rules-paths.yml +92 -0
  89. package/lib/audit-rules/audit-rules-performance.yml +207 -0
  90. package/lib/audit-rules/audit-rules-php.yml +22 -0
  91. package/lib/audit-rules/audit-rules-private.yml +24 -0
  92. package/lib/audit-rules/audit-rules-python.yml +106 -0
  93. package/lib/audit-rules/audit-rules-robustness.yml +27 -0
  94. package/lib/audit-rules/audit-rules-rust.yml +22 -0
  95. package/lib/audit-rules/audit-rules-structure.yml +159 -0
  96. package/lib/audit-rules/audit-rules-swift.yml +22 -0
  97. package/lib/audit-rules/audit-rules-template.yml +108 -0
  98. package/lib/checks/button-bind.js +276 -0
  99. package/lib/checks/common.js +170 -0
  100. package/lib/checks/credential-file.js +43 -0
  101. package/lib/checks/dataflow.js +40 -0
  102. package/lib/checks/dispatch.js +112 -0
  103. package/lib/checks/dup-code.js +69 -0
  104. package/lib/checks/dup-const.js +232 -0
  105. package/lib/checks/file-health.js +150 -0
  106. package/lib/checks/filter.js +131 -0
  107. package/lib/checks/folder.js +173 -0
  108. package/lib/checks/hardcoded-path.js +98 -0
  109. package/lib/checks/index.js +46 -0
  110. package/lib/checks/io.js +66 -0
  111. package/lib/checks/magic-number.js +42 -0
  112. package/lib/checks/npm-json.js +273 -0
  113. package/lib/checks/private.js +63 -0
  114. package/lib/checks/regex.js +256 -0
  115. package/lib/checks/semantic.js +134 -0
  116. package/lib/checks/structural.js +274 -0
  117. package/lib/cli/commands-account.mjs +107 -0
  118. package/lib/cli/commands-audit.mjs +144 -0
  119. package/lib/cli/commands-doc.mjs +127 -0
  120. package/lib/cli/commands-vcs.mjs +175 -0
  121. package/lib/client/index.js +162 -0
  122. package/lib/client-parts/00-loader.js +33 -0
  123. package/lib/client-parts/01-const.js +207 -0
  124. package/lib/client-parts/02-utils.js +62 -0
  125. package/lib/client-parts/03-icons.js +12 -0
  126. package/lib/client-parts/10-account.js +83 -0
  127. package/lib/client-parts/11-browser.js +95 -0
  128. package/lib/client-parts/20-repo.js +374 -0
  129. package/lib/client-parts/21-audit.js +301 -0
  130. package/lib/client-parts/22-settings.js +146 -0
  131. package/lib/client-parts/23-npm.js +383 -0
  132. package/lib/client-parts/30-page.js +56 -0
  133. package/lib/client-parts/40-controller.js +1092 -0
  134. package/lib/client-parts/41-actions.js +279 -0
  135. package/lib/client-parts/99-apply.js +72 -0
  136. package/lib/client.js +3195 -0
  137. package/lib/commit-push.js +144 -0
  138. package/lib/context/index.js +363 -0
  139. package/lib/core/atomic-json.js +98 -0
  140. package/lib/core/config.js +40 -0
  141. package/lib/core/credentials.js +274 -0
  142. package/lib/core/endpoints.js +109 -0
  143. package/lib/core/exec.js +162 -0
  144. package/lib/exempt/index.js +292 -0
  145. package/lib/fs/edit-after-read.js +103 -0
  146. package/lib/fsx.js +87 -0
  147. package/lib/git/account-status.js +140 -0
  148. package/lib/git/account.js +233 -0
  149. package/lib/git/api.js +136 -0
  150. package/lib/git/atomic-json.js +6 -0
  151. package/lib/git/browse.js +38 -0
  152. package/lib/git/clone-download.js +397 -0
  153. package/lib/git/clone-history-mode.js +143 -0
  154. package/lib/git/clone-history.js +175 -0
  155. package/lib/git/clone-jobs.js +250 -0
  156. package/lib/git/clone-replay-io.js +172 -0
  157. package/lib/git/clone-replay.js +275 -0
  158. package/lib/git/clone.js +445 -0
  159. package/lib/git/cloud.js +46 -0
  160. package/lib/git/commit-message.js +141 -0
  161. package/lib/git/config.js +6 -0
  162. package/lib/git/cred-env.js +88 -0
  163. package/lib/git/credentials.js +6 -0
  164. package/lib/git/endpoints.js +6 -0
  165. package/lib/git/exec.js +6 -0
  166. package/lib/git/identity-rewrite.js +297 -0
  167. package/lib/git/identity.js +150 -0
  168. package/lib/git/ignore.js +69 -0
  169. package/lib/git/index.js +41 -0
  170. package/lib/git/module-splitter.js +47 -0
  171. package/lib/git/post-push.js +101 -0
  172. package/lib/git/push-diagnose.js +142 -0
  173. package/lib/git/push.js +470 -0
  174. package/lib/git/remote-resolve.js +146 -0
  175. package/lib/git/remote.js +128 -0
  176. package/lib/git/repo-index.js +512 -0
  177. package/lib/git/repos.js +235 -0
  178. package/lib/git/scan-runner.js +159 -0
  179. package/lib/git/sensitive.js +134 -0
  180. package/lib/git/transport.js +430 -0
  181. package/lib/git/visibility.js +35 -0
  182. package/lib/git/wrapped-git.js +68 -0
  183. package/lib/http/index.js +170 -0
  184. package/lib/index.js +24 -0
  185. package/lib/link-check/index.js +187 -0
  186. package/lib/npm/account.js +64 -0
  187. package/lib/npm/install.js +211 -0
  188. package/lib/npm/npmrc.js +56 -0
  189. package/lib/npm/publish.js +167 -0
  190. package/lib/npm/registry.js +147 -0
  191. package/lib/plugin/auto-detect.js +92 -0
  192. package/lib/plugin/auto-push.js +154 -0
  193. package/lib/plugin/index.js +250 -0
  194. package/lib/readme-templates/readme.yml +38 -0
  195. package/lib/rule/compilers/credential.js +62 -0
  196. package/lib/rule/compilers/dataflow.js +38 -0
  197. package/lib/rule/compilers/file-health.js +75 -0
  198. package/lib/rule/compilers/frontend.js +86 -0
  199. package/lib/rule/compilers/func.js +35 -0
  200. package/lib/rule/compilers/helpers.js +71 -0
  201. package/lib/rule/compilers/index.js +29 -0
  202. package/lib/rule/compilers/link-semantic.js +45 -0
  203. package/lib/rule/compilers/list-kinds.js +12 -0
  204. package/lib/rule/compilers/numeric-kinds.js +66 -0
  205. package/lib/rule/compilers/regex.js +78 -0
  206. package/lib/rule/compilers/structure.js +80 -0
  207. package/lib/rule/compilers.js +17 -0
  208. package/lib/rule/homoglyph.js +45 -0
  209. package/lib/rule/loader.js +270 -0
  210. package/lib/rule/registry.js +115 -0
  211. package/lib/rule/scope.js +67 -0
  212. package/lib/score/docs-score.js +166 -0
  213. package/lib/score/index.js +140 -0
  214. package/lib/self/index.js +193 -0
  215. package/lib/skip-dirs.js +64 -0
  216. package/lib/tool-probes.json +50 -0
  217. package/lib/user-requirements.json +14 -0
  218. package/lib/vendor/js-yaml/LICENSE +21 -0
  219. package/lib/vendor/js-yaml/js-yaml.mjs +3073 -0
  220. package/package.json +95 -4
  221. package/scripts/__pycache__/module-splitter.cpython-38.pyc +0 -0
  222. package/scripts/audit-ext/_example-readme-present.mjs +34 -0
  223. package/scripts/audit-ext/variable-min-length.mjs +102 -0
  224. package/scripts/audit-runner.mjs +35 -0
  225. package/scripts/audit-runtime-check.mjs +129 -0
  226. package/scripts/browser-page-probe.mjs +271 -0
  227. package/scripts/build-client.mjs +119 -0
  228. package/scripts/check.mjs +88 -0
  229. package/scripts/clean-date-comments.py +102 -0
  230. package/scripts/doc-drift.mjs +200 -0
  231. package/scripts/doc-func.mjs +212 -0
  232. package/scripts/doc-tree.mjs +456 -0
  233. package/scripts/doc-version.mjs +220 -0
  234. package/scripts/frontend-preview-check.mjs +124 -0
  235. package/scripts/hot-path-probe-cjs.cjs +71 -0
  236. package/scripts/hot-path-probe-fs-shim.mjs +28 -0
  237. package/scripts/hot-path-probe-fsp-shim.mjs +31 -0
  238. package/scripts/hot-path-probe.mjs +153 -0
  239. package/scripts/module-splitter.py +800 -0
  240. package/scripts/platform-scan.mjs +168 -0
  241. package/scripts/preview-gen.mjs +489 -0
  242. package/scripts/preview-local-runner.mjs +55 -0
  243. package/scripts/preview-server-direct.mjs +116 -0
  244. package/scripts/preview-server.mjs +305 -0
  245. package/scripts/preview-slot-data.mjs +123 -0
  246. package/scripts/probe-recheck.mjs +47 -0
  247. package/scripts/readme-gen.mjs +268 -0
  248. package/scripts/rename-locator.mjs +97 -0
  249. package/scripts/rule-switch.mjs +97 -0
  250. package/scripts/rules-solo-audit.mjs +173 -0
  251. package/scripts/scan-file-io.mjs +713 -0
  252. package/scripts/scan-hardcoded-paths.mjs +125 -0
  253. package/scripts/scan-repos.mjs +167 -0
  254. package/scripts/scan-version.mjs +122 -0
  255. package/scripts/scrub-user-wording.mjs +420 -0
  256. package/scripts/symbol-index.mjs +85 -0
  257. package/scripts/sync-plugin-install.mjs +223 -0
  258. package/scripts/sync-plugin.mjs +279 -0
  259. package/scripts/verify-prestep.mjs +100 -0
  260. package/skills/dev/audit-rule-authoring.md +58 -0
  261. package/skills/dev/dsh-git-push.md +323 -0
  262. package/skills/dev/git-push-live-fix.md +45 -0
  263. package/skills/dsh-repo-index.md +35 -0
  264. package/skills/guide/guide-audit.md +167 -0
  265. package/skills/guide/guide-cli-scripts.md +104 -0
  266. package/skills/guide/guide-clone-repos.md +173 -0
  267. package/skills/guide/guide-commit-push.md +156 -0
  268. package/skills/guide/guide-inject-ui.md +166 -0
  269. package/skills/guide/guide-slash-completion.md +118 -0
  270. package/skills/workflow/README.md +21 -0
  271. package/skills/workflow/git-commit-discipline.md +68 -0
  272. package/skills/workflow/git-project-startup.md +85 -0
  273. package/skills/workflow/git-rebuild-process.md +57 -0
  274. package/skills/workflow/github-operations.md +91 -0
  275. package/skills/workflow/readme-sync-git-md.md +28 -0
  276. package/skills/workflow/task-completion-report.md +73 -0
  277. package/skills/workflow/tool-json-add-ask.md +35 -0
  278. package/skills/workflow/versioning-rule.md +211 -0
@@ -0,0 +1,200 @@
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();
@@ -0,0 +1,212 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * dsh-git-push — 函数列表文档生成器(doc-func:统一替代 functions-doc + func-index 两个旧脚本——函数清单由 AST 真实生成,避免手工维护漂移)
4
+ * dsh-skip-i18n: 用户可见文案硬编码为产品设计
5
+ *
6
+ * 分体式文档三兄弟之一(doc-tree 文件树 / doc-func 函数列表 / doc-version 版本列表)。
7
+ * 扫描项目 JS/ESM 文件提取函数(name/行号/行数/签名),生成 markdown 函数列表,
8
+ * 写入宿主 md(README 有 dshgp-functions 标记块用 README,否则 docs/ 带块 md)。
9
+ *
10
+ * 用法:
11
+ * node scripts/doc-func.mjs gen [--root <项目根>] # 打印函数列表文本(不写文件)
12
+ * node scripts/doc-func.mjs apply [--root <项目根>] # 写入宿主 md(自动探测)
13
+ * node scripts/doc-func.mjs check [--root <项目根>] # 比对宿主块与最新列表(漂移报错)
14
+ * --include <glob> 可选限定扫描范围(缺省 lib/ scripts/ test/ 下的 .js/.mjs)
15
+ */
16
+ import { readFileSync, writeFileSync, readdirSync, statSync, 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
+
21
+ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
22
+ const MARKER = 'dshgp-functions';
23
+ const MARK_START = `<!-- ${MARKER}:start -->`;
24
+ const MARK_END = `<!-- ${MARKER}:end -->`;
25
+ /** 默认扫描目录(可 --include 覆盖)。 */
26
+ const DEFAULT_SCAN_DIRS = ['lib', 'scripts', 'test'];
27
+
28
+ /* ─────────── 函数扫描(自包含,原 func-index 逻辑) ─────────── */
29
+
30
+ function escapeReg(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
31
+
32
+ function stripComment(line) {
33
+ return String(line).replace(/\/\/.*$/, '');
34
+ }
35
+
36
+ /** 从 startIndex 找函数体结束行(括号配对)。 */
37
+ function findBlockEnd(lines, startIdx) {
38
+ let depth = 0;
39
+ let started = false;
40
+ for (let i = startIdx; i < lines.length; i++) {
41
+ const line = stripComment(lines[i]);
42
+ for (const ch of line) {
43
+ if (ch === '{') { depth++; started = true; }
44
+ else if (ch === '}') { depth--; }
45
+ }
46
+ if (started && depth <= 0 && i > startIdx) return { end: i, depth };
47
+ }
48
+ return { end: lines.length - 1, depth };
49
+ }
50
+
51
+ function detectFunction(lines, i) {
52
+ const t = stripComment(lines[i]).trim();
53
+ let match = t.match(/^(?:export\s+)?(?:default\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/);
54
+ if (match) return { name: match[1], kind: 'function', defLine: i };
55
+ match = t.match(/^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s+)?function\s*\(/);
56
+ if (match) return { name: match[1], kind: 'var-function', defLine: i };
57
+ match = t.match(/^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\([^=)]*?\)\s*=>\s*\{?[^;{}]*\}?;?\s*$/);
58
+ if (match) return { name: match[1], kind: 'arrow', defLine: i };
59
+ return null;
60
+ }
61
+
62
+ /** 扫描单文件 → { file, funcs, totalLines }。 */
63
+ export function scanFileFuncs(file, textOverride) {
64
+ // textOverride:调用方已有全文时直接传进来,省掉一次读盘 + 一次 split
65
+ // (2026-10-09 热路径实测:事实层生成时同一文件被读 3 次 → 传文本后降到 1 次;NFS/CIFS 上收益更明显)
66
+ let text;
67
+ if (textOverride === undefined) {
68
+ try { text = readFileSync(file, 'utf8'); } catch (e) { return { file, funcs: [], totalLines: 0, error: e.message }; }
69
+ } else {
70
+ text = String(textOverride);
71
+ }
72
+ const lines = text.split('\n');
73
+ const funcs = [];
74
+ for (let i = 0; i < lines.length; i++) {
75
+ const trimmed = lines[i].trim();
76
+ if (!trimmed || trimmed.startsWith('//') || trimmed.startsWith('/*') || trimmed.startsWith('*')) continue;
77
+ const hit = detectFunction(lines, i);
78
+ if (!hit) continue;
79
+ let bodyStart = i;
80
+ if (!stripComment(lines[i]).includes('{')) {
81
+ // 找 { 所在行(多行签名)。arrow 表达式体(如 `() => 1`)无 { → 单行函数直接收尾。
82
+ if (hit.kind === 'arrow') {
83
+ funcs.push({
84
+ name: hit.name, kind: hit.kind,
85
+ defLine: i + 1, endLine: i + 1, lines: 1,
86
+ signature: String(lines[i] || '').trim(),
87
+ });
88
+ continue;
89
+ }
90
+ let j = i; let depth = 0;
91
+ while (j < lines.length) {
92
+ depth += (stripComment(lines[j]).match(/\{/g) || []).length;
93
+ if (depth > 0) break;
94
+ j++;
95
+ }
96
+ bodyStart = j;
97
+ if (bodyStart >= lines.length) continue;
98
+ }
99
+ const { end } = findBlockEnd(lines, bodyStart);
100
+ funcs.push({
101
+ name: hit.name, kind: hit.kind,
102
+ defLine: i + 1, endLine: end + 1, lines: end - i + 1,
103
+ signature: String(lines[i] || '').trim(),
104
+ });
105
+ }
106
+ funcs.sort((a, b) => a.defLine - b.defLine);
107
+ return { file, funcs, totalLines: lines.length };
108
+ }
109
+
110
+ /** 收集扫描文件(root 下 lib/scripts/test 的 .js/.mjs,或 --include 指定目录)。 */
111
+ export function collectFuncFiles(root, includeDirs = DEFAULT_SCAN_DIRS) {
112
+ const out = [];
113
+ const walk = (dir, depth) => {
114
+ if (depth > 6) return;
115
+ let entries = [];
116
+ try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
117
+ for (const e of entries) {
118
+ if (e.name === 'node_modules' || e.name === '.git' || e.name === 'docs' || e.name === 'skills') continue;
119
+ const full = join(dir, e.name);
120
+ if (e.isDirectory()) walk(full, depth + 1);
121
+ else if (/\.(js|mjs)$/.test(e.name) && !e.name.endsWith('.min.js')) out.push(full);
122
+ }
123
+ };
124
+ for (const d of includeDirs) walk(join(root, d), 0);
125
+ return out.sort();
126
+ }
127
+
128
+ /** 生成函数列表 markdown(宿主块内容)。 */
129
+ export function buildFuncListText(root, includeDirs = DEFAULT_SCAN_DIRS) {
130
+ const files = collectFuncFiles(root, includeDirs);
131
+ const lines = [];
132
+ let total = 0;
133
+ for (const f of files) {
134
+ const r = scanFileFuncs(f);
135
+ if (!r.funcs.length) continue;
136
+ total += r.funcs.length;
137
+ const rel = relative(root, f);
138
+ lines.push(`### ${rel}(${r.totalLines} 行 · ${r.funcs.length} 个函数)`);
139
+ lines.push('');
140
+ lines.push('| 函数 | 行号 | 行数 | 签名 |');
141
+ lines.push('|------|------|------|------|');
142
+ for (const fn of r.funcs) {
143
+ lines.push(`| \`${fn.name}\` | ${fn.defLine}-${fn.endLine} | ${fn.lines} | \`${fn.signature.replace(/\|/g, '\\|')}\` |`);
144
+ }
145
+ lines.push('');
146
+ }
147
+ return { text: `## 函数列表\n\n${lines.join('\n')}`, files: files.length, funcs: total };
148
+ }
149
+
150
+ /** 找宿主 md 内的 dshgp-functions 标记块。 */
151
+ function findBlock(text) {
152
+ const s = text.indexOf(MARK_START);
153
+ const e = text.indexOf(MARK_END);
154
+ if (s === -1 || e === -1 || e <= s) return null;
155
+ return { start: s, end: e, content: text.slice(s + MARK_START.length, e) };
156
+ }
157
+
158
+ /** 替换/插入标记块。无块时追加到文件尾。 */
159
+ export function applyFuncBlock(text, newContent) {
160
+ const block = findBlock(text);
161
+ if (block) return text.slice(0, block.start) + MARK_START + '\n' + newContent + '\n' + MARK_END + text.slice(block.end + MARK_END.length);
162
+ return text.replace(/\s*$/, '\n') + `\n${MARK_START}\n${newContent}\n${MARK_END}\n`;
163
+ }
164
+
165
+ /** 比对宿主块与最新列表。返回 { ok, issues, latest }。 */
166
+ export function checkFuncDrift({ hostPath, root, includeDirs = DEFAULT_SCAN_DIRS } = {}) {
167
+ const { text: latest } = buildFuncListText(root, includeDirs);
168
+ const host = existsSync(hostPath) ? readFileSync(hostPath, 'utf8') : '';
169
+ const block = findBlock(host);
170
+ const issues = [];
171
+ if (!block) issues.push({ type: 'no-block', msg: `${basename(hostPath)} 无函数列表标记块(${MARK_START} … ${MARK_END}),先 apply 生成` });
172
+ else {
173
+ const cur = block.content.trim();
174
+ const expected = latest.trim();
175
+ if (cur !== expected) issues.push({ type: 'drift', msg: `函数列表与最新扫描不一致(运行 doc-func.mjs apply 更新)` });
176
+ }
177
+ return { ok: issues.length === 0, issues, latest };
178
+ }
179
+
180
+ /* ─────────── CLI ─────────── */
181
+
182
+ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
183
+ const args = process.argv.slice(2);
184
+ const cmd = args[0];
185
+ const rootIdx = args.indexOf('--root');
186
+ const root = rootIdx !== -1 && args[rootIdx + 1] ? resolve(args[rootIdx + 1]) : ROOT;
187
+ const host = findMarkedHostMd(root, MARKER);
188
+ const out = (msg) => console.log(msg);
189
+
190
+ if (cmd === 'gen') {
191
+ const r = buildFuncListText(root);
192
+ out(r.text);
193
+ out(`\n(扫描 ${r.files} 文件 · ${r.funcs} 函数;apply 写入 ${relative(root, host) || 'README.md'})`);
194
+ process.exit(0);
195
+ }
196
+ if (cmd === 'apply') {
197
+ const r = buildFuncListText(root);
198
+ const hostText = existsSync(host) ? readFileSync(host, 'utf8') : '';
199
+ writeFileSync(host, applyFuncBlock(hostText, r.text), 'utf8');
200
+ out(`✅ 已写入函数列表 → ${relative(root, host) || 'README.md'}(${r.files} 文件 · ${r.funcs} 函数)`);
201
+ process.exit(0);
202
+ }
203
+ if (cmd === 'check') {
204
+ const r = checkFuncDrift({ hostPath: host, root });
205
+ if (r.ok) { out(`✅ 函数列表与扫描一致(${relative(root, host) || 'README.md'})`); process.exit(0); }
206
+ out('❌ 函数列表存在差异:');
207
+ for (const i of r.issues) out(' - ' + i.msg);
208
+ process.exit(1);
209
+ }
210
+ out('用法: node scripts/doc-func.mjs <gen|apply|check> [--root <项目根>]');
211
+ process.exit(1);
212
+ }