dsh-git-push 2.18.2 → 2.20.17

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 (90) hide show
  1. package/.gitignore +4 -0
  2. package/README.md +12 -5
  3. package/cli-audit.mjs +141 -0
  4. package/cli-tool.mjs +86 -0
  5. package/cli.mjs +116 -324
  6. package/lib/ARCHITECTURE.md +3 -0
  7. package/lib/app/audit-api.js +1 -1
  8. package/lib/app/command-registry.js +16 -3
  9. package/lib/app/constants.js +9 -0
  10. package/lib/app/handlers/clone.js +12 -3
  11. package/lib/app/handlers/http-constants.js +11 -2
  12. package/lib/app/handlers/npm.js +4 -2
  13. package/lib/app/handlers/repos.js +10 -1
  14. package/lib/app/handlers/settings.js +9 -1
  15. package/lib/app/http-handlers.js +24 -3
  16. package/lib/app/inject-text.js +1 -0
  17. package/lib/app/schema-audit.js +42 -0
  18. package/lib/app/schema.js +19 -19
  19. package/lib/app/scope-check.js +69 -0
  20. package/lib/app/settings-bridge.js +51 -0
  21. package/lib/app/tool-call.js +56 -7
  22. package/lib/ast/credential.js +130 -14
  23. package/lib/ast/dataflow.js +127 -10
  24. package/lib/ast/index.js +2 -0
  25. package/lib/ast/naming.js +9 -1
  26. package/lib/ast/scope-collisions.js +228 -0
  27. package/lib/ast/treesitter.js +142 -1
  28. package/lib/audit/history.js +1 -1
  29. package/lib/audit/orchestrate.js +93 -6
  30. package/lib/audit/scope-policy.js +110 -0
  31. package/lib/audit-rules/audit-rules-dsh.yml +16 -1
  32. package/lib/audit-rules/audit-rules-nodejs.yml +21 -6
  33. package/lib/audit-rules/audit-rules-paths.yml +7 -1
  34. package/lib/audit-ui-sdk/contract.js +117 -0
  35. package/lib/audit-ui-sdk/index.js +17 -0
  36. package/lib/checks/common.js +4 -4
  37. package/lib/checks/dispatch.js +5 -0
  38. package/lib/checks/index.js +2 -0
  39. package/lib/checks/regex.js +8 -3
  40. package/lib/checks/scope-collision.js +68 -0
  41. package/lib/cli/commands-audit.mjs +13 -18
  42. package/lib/cli/commands-tool.mjs +93 -0
  43. package/lib/cli/commands-vcs.mjs +2 -1
  44. package/lib/cli/shared.mjs +448 -0
  45. package/lib/client-parts/{account.js → git/account.js} +1 -1
  46. package/lib/client-parts/{actions.js → git/actions.js} +26 -11
  47. package/lib/client-parts/{apply.js → git/apply.js} +1 -1
  48. package/lib/client-parts/{browser.js → git/browser.js} +1 -1
  49. package/lib/client-parts/{const.js → git/const.js} +6 -1
  50. package/lib/client-parts/{controller.js → git/controller.js} +23 -11
  51. package/lib/client-parts/{icons.js → git/icons.js} +1 -1
  52. package/lib/client-parts/{loader.js → git/loader.js} +1 -1
  53. package/lib/client-parts/{npm.js → git/npm.js} +1 -1
  54. package/lib/client-parts/{page.js → git/page.js} +11 -21
  55. package/lib/client-parts/{repo.js → git/repo.js} +1 -1
  56. package/lib/client-parts/{settings.js → git/settings.js} +1 -1
  57. package/lib/client-parts/{utils.js → git/utils.js} +1 -1
  58. package/lib/client.js +75 -354
  59. package/lib/commit-push/pre-commit-engine.js +388 -0
  60. package/lib/commit-push.js +44 -17
  61. package/lib/exempt/index.js +5 -2
  62. package/lib/git/ignore.js +6 -4
  63. package/lib/git/init-compat.js +83 -4
  64. package/lib/git/push.js +25 -2
  65. package/lib/git/sensitive.js +30 -1
  66. package/lib/git/transport.js +31 -10
  67. package/lib/http/index.js +82 -10
  68. package/lib/lint-adapter/detect.js +161 -0
  69. package/lib/lint-adapter/index.js +50 -0
  70. package/lib/lint-adapter/runner.js +133 -0
  71. package/lib/npm/npmrc.js +22 -5
  72. package/lib/rule/compilers/structure.js +24 -0
  73. package/lib/score/index.js +36 -4
  74. package/lib/self/index.js +1 -1
  75. package/package.json +25 -2
  76. package/scripts/audit-gate.mjs +235 -0
  77. package/scripts/build-client.mjs +15 -8
  78. package/scripts/bump-version.mjs +20 -5
  79. package/scripts/check-js-scope.mjs +87 -0
  80. package/scripts/check.mjs +51 -4
  81. package/scripts/scan-file-io.mjs +5 -1
  82. package/scripts/scan-version.mjs +10 -7
  83. package/skills/dev/dsh-git-push.md +70 -2
  84. package/skills/guide/guide-audit.md +11 -11
  85. package/skills/guide/guide-cli-scripts.md +3 -3
  86. package/skills/guide/guide-commit-push.md +2 -2
  87. package/skills/guide/guide-inject-ui.md +0 -16
  88. package/assets/start.sh +0 -396
  89. package/scripts/scan-hardcoded-paths.mjs +0 -125
  90. /package/lib/client-parts/{audit.js → audit/audit.js} +0 -0
@@ -0,0 +1,110 @@
1
+ /**
2
+ * 拼接产物作用域契约的**读取层**(中立模块:工具/独立脚本/审计检查三方共用一份判定)。
3
+ *
4
+ * 为什么单独成模块:同一件事有三个入口(`scope_check` 工具、`scripts/check-js-scope.mjs`、
5
+ * 审计规则 kind=scope-collision),「按文件所属项目取契约」的判定一旦各写一份就会漂移。
6
+ * 放在 lib/app/ 会被 lib/checks/ 反向依赖(现有链路是 app → audit → checks,
7
+ * checks → app 会成环);与 lib/audit/client-entry.js 同款处理:共用逻辑下沉中立模块,
8
+ * 依赖方向保持单向(checks → audit/scope-policy 是叶子模块,无回指)。
9
+ *
10
+ * 核心约定:`dshgp_` 前缀与「顶层零声明」都是**各项目自己的契约**,不是通用规范。
11
+ * 拿本项目的约定去要求别人的文件,会刷出一屏「缺少 dshgp_ 前缀」,把真正的同帧重名淹掉。
12
+ * ① 调用方显式给定 prefix/allowlist → 以显式值为准(调用方明确要求);
13
+ * ② 否则从文件所在目录向上找最近的 package.json,读其 `dshScopeCheck`;
14
+ * ③ 都没有 → 前缀留空、不要求顶层零声明,**只查同帧重名**(唯一通用项)。
15
+ */
16
+
17
+ import { existsSync, readFileSync } from 'node:fs';
18
+ import { dirname, join, relative, resolve } from 'node:path';
19
+
20
+ /** 策略来源(输出头自证:避免「继承了本仓默认值」被误读成对方的约定)。 */
21
+ export const POLICY_SOURCE = {
22
+ CLI: '命令行',
23
+ PROJECT: '项目 package.json',
24
+ BUILTIN: '内置默认(只查同帧重名)',
25
+ };
26
+
27
+ /** 路径归一化:去掉前导 `./`、反斜杠统一成 `/`(声明值与相对路径两边都用它比)。 */
28
+ function normRelPath(value) {
29
+ return String(value || '').replace(/\\/g, '/').replace(/^\.\//, '');
30
+ }
31
+
32
+ /**
33
+ * 目录 → 最近的 package.json 路径缓存('' = 一路到根都没有)。
34
+ *
35
+ * 为什么需要:审计逐文件调用本模块,全仓 400+ 个 js 就要做 400+ 次「向上找 package.json」;
36
+ * 在 CIFS/HFS 挂载上 stat 单次约 2.8ms,实测这一项 1.2s(占比虽小但纯浪费)。
37
+ * TTL 取 1s:一次审计内连续调用几乎全命中,而两次审计之间(≥1s)必然重新读,
38
+ * 不会把「刚改了 dshScopeCheck 又立刻审计」读成旧值。
39
+ */
40
+ const DIR_LOOKUP_TTL_MS = 1000;
41
+ const dirLookupCache = new Map(); // dir → { at, configPath }
42
+
43
+ /** 向上找最近的 package.json(带 1s 缓存)。 */
44
+ function findConfigPath(startDir, now) {
45
+ const cached = dirLookupCache.get(startDir);
46
+ if (cached && now - cached.at < DIR_LOOKUP_TTL_MS) return cached.configPath;
47
+ let found = '';
48
+ let dir = startDir;
49
+ for (;;) {
50
+ const candidate = join(dir, 'package.json');
51
+ if (existsSync(candidate)) { found = candidate; break; }
52
+ const parent = dirname(dir);
53
+ if (parent === dir) break; // 到根了还没找到 ⇒ 无声明
54
+ dir = parent;
55
+ }
56
+ dirLookupCache.set(startDir, { at: now, configPath: found });
57
+ return found;
58
+ }
59
+
60
+ /**
61
+ * 读某个文件所属项目的作用域契约。
62
+ *
63
+ * @param {string} file 目标文件路径(绝对路径最稳;相对路径按进程 cwd 解析)
64
+ * @returns {{
65
+ * declared: boolean, 是否找到了显式声明(决定「契约类检查」跑不跑)
66
+ * isDeclaredArtifact: boolean, 当前文件是否在该项目声明的 files 清单里
67
+ * prefix: string, allowlist: string[], topLevelMustBeEmpty: boolean,
68
+ * files: string[], configPath: string, relFromConfig: string, source: string
69
+ * }}
70
+ * `isDeclaredArtifact` 必须为 true 才允许套用 prefix / 顶层零声明:`files` 清单就是
71
+ * 「哪些文件是拼接产物」的声明——不在清单里的文件(如分片源码)套用前缀会把
72
+ * 片段里的局部变量全部误判成缺前缀。
73
+ */
74
+ export function readProjectScopePolicy(file = '') {
75
+ const target = resolve(file);
76
+ const builtin = {
77
+ declared: false,
78
+ isDeclaredArtifact: false,
79
+ prefix: '',
80
+ allowlist: [],
81
+ topLevelMustBeEmpty: false,
82
+ files: [],
83
+ configPath: '',
84
+ relFromConfig: '',
85
+ source: POLICY_SOURCE.BUILTIN,
86
+ };
87
+ const configPath = findConfigPath(dirname(target), Date.now());
88
+ if (!configPath) return builtin; // 一路到根都没有 package.json ⇒ 按「无声明」处理
89
+ let own;
90
+ try {
91
+ own = JSON.parse(readFileSync(configPath, 'utf8'))?.dshScopeCheck;
92
+ } catch {
93
+ return builtin; // package.json 损坏 → 按「无声明」处理,不抛给调用方
94
+ }
95
+ if (!own || typeof own !== 'object') return builtin; // 找到所属项目但没声明 ⇒ 不套别人的规范
96
+ const files = Array.isArray(own.files) ? own.files.map(String) : [];
97
+ const configDir = dirname(configPath);
98
+ const relFromConfig = normRelPath(relative(configDir, target));
99
+ return {
100
+ declared: true,
101
+ isDeclaredArtifact: files.some((rel) => normRelPath(rel) === relFromConfig),
102
+ prefix: String(own.prefix || ''),
103
+ allowlist: Array.isArray(own.allowlist) ? own.allowlist.map(String) : [],
104
+ topLevelMustBeEmpty: own.topLevelMustBeEmpty === true,
105
+ files,
106
+ configPath,
107
+ relFromConfig,
108
+ source: POLICY_SOURCE.PROJECT,
109
+ };
110
+ }
@@ -159,4 +159,19 @@ rules:
159
159
  patterns:
160
160
  - "\\b(addRoute|addHandler|registerRoute|useRoute)\\s*\\|\\|"
161
161
  fixable: true
162
- mitigation: "按官方真实 API 写(webServer.register({ kind:'prefix', path, handler }));接线失败必须 return false 并告警,不得静默吞掉"
162
+ mitigation: "按官方真实 API 写(webServer.register({ kind:'prefix', path, handler }));接线失败必须 return false 并告警,不得静默吞掉"
163
+ # ── ⑦ 分片拼接作用域(多段 JS 拼成单文件产物时 var/function 同名静默覆盖)──
164
+ # 为什么不用 patterns:这是**跨声明**的语义判定(同名次数 + 真实作用域帧),
165
+ # 单行正则做不到;由 kind=scope-collision 的编译器 + lib/ast/scope-collisions.js 执行。
166
+ # 契约来源:前缀 / 顶层零声明 / 产物文件清单一律取自**被审项目自己**的 package.json
167
+ # (dshScopeCheck,读在 lib/audit/scope-policy.js)——规则包跨仓库共享,
168
+ # 把 dshgp_ 写在这里会让所有被审项目都收到「缺少 dshgp_ 前缀」这类无关告警。
169
+ - id: dsh/scope-collision
170
+ kind: "scope-collision"
171
+ name: "分片拼接作用域撞名(var/function 静默覆盖)"
172
+ category: "structure"
173
+ severity: "error"
174
+ description: "多段 JS 拼进同一作用域(分片拼 factory / 多个 <script> 引入 / cat a.js b.js > bundle.js)时,同一函数帧内 function/const/let/class 同名会让后者顶掉前者或让整份产物 SyntaxError,且运行期可能毫无报错线索;判定按真实作用域帧,两个不同函数里的同名局部变量不算撞名。顶层声明与裸名在拼接场景还会与其它脚本撞名(该两项只有项目自己在 package.json 声明 dshScopeCheck 时才查)。"
175
+ exts: ["js", "mjs", "cjs"]
176
+ fixable: false
177
+ mitigation: "① 同帧重名必须改名(function/const/let/class 是真缺陷,纯 var 重复至少应合并);② 拼接产物保持文件顶层零声明;③ 共享作用域内的声明加项目约定的前缀,并把该约定写进项目 package.json 的 dshScopeCheck(files/prefix/allowlist/topLevelMustBeEmpty)"
@@ -63,7 +63,14 @@ rules:
63
63
  category: "readability"
64
64
  severity: "warning"
65
65
  description: "函数名 ≤2 字符是缩写(如 gU),无法从名字猜出含义"
66
- pattern: "\\bfunction\\s+[a-zA-Z_$][a-zA-Z0-9_$]{0,1}\\s*\\("
66
+ patterns:
67
+ - "\\bfunction\\s+[a-zA-Z_$][a-zA-Z0-9_$]{0,1}\\s*\\("
68
+ # 方法定义行(class A { gh() {} } / const o = { ef() {} })不含 function 关键字,
69
+ # 第一条 pattern 结构上不可能命中它们 ⇒ 候选行都进不来,树化后照样漏报(实测踩过:
70
+ # allow 精筛前必须先过初筛)。这里只做**粗筛**(行首短标识符 + 左括号),
71
+ # 是否真是「定义」由 short-func-name 精筛(语法树 method_definition 节点)判定——
72
+ # 因此 ` ab(1);` 这类调用行虽进候选,也不会被报。
73
+ - "^\\s*[a-zA-Z_$][a-zA-Z0-9_$]{0,1}\\s*\\("
67
74
  # 2026-09-13 误报修复(正则初筛 → AST 精筛):i18n 领域标准缩写(tr/t/L 等翻译、
68
75
  # 字典函数名)长度 ≤2 但含义公认,纯正则命中即报会把它们当「无法猜出含义」报掉。
69
76
  # astConfirmKind: short-func-name → token 级判定(checkShortFunctionNameAst):
@@ -348,12 +355,20 @@ rules:
348
355
  # · 引号内内容收紧为 `[^'"\s]{8,}`——真实凭据较长,短占位/空串不参与初筛
349
356
  # (AST 精筛仍按 isMeaningfulCredentialValue 判占位符,双层不矛盾)。
350
357
  astConfirmKind: credential-value
358
+ # 初筛在 `=`/`:` 与引号之间允许 ≤2 字符的**字符串前缀**(Python b"…"/rb'…'、f"…"):
359
+ # 原写法 `=\s*['\"]` 在 `SECRET_KEY = b"…"` 上因夹着 b 直接断链,bytes 真凭据
360
+ # 连候选行都进不来(外部仓库实测漏报)。放宽只影响初筛覆盖面,是否真报仍由
361
+ # credential-value 精筛(树/ token)判语义与值形状决定,不会新增误报形态。
362
+ # 凭据词后允许词尾段(`(?![A-Za-z])\\w*`):`SECRET_KEY =` / `API_KEY_ID =` 这类
363
+ # 下划线复合标识符此前因「凭据词后不直接接等号」而漏出候选(外部仓库实测
364
+ # APP_UPDATE_TOKEN_SECRET = b"…" 整行不报);`(?![A-Za-z])` 保证 tokenizer /
365
+ # cookieMonster 这类「凭据词只是单词前缀」的情况仍不进候选。
351
366
  patterns:
352
- - "(?<![?&/])password\\s*[=:]+\\s*['\"][^'\"\\s]{8,}['\"]"
353
- - "(?<![?&/])secret\\s*[=:]+\\s*['\"][^'\"\\s]{8,}['\"]"
354
- - "(?<![?&/])api[_-]?key\\s*[=:]+\\s*['\"][^'\"\\s]{8,}['\"]"
355
- - "(?<![?&/])token\\s*[=:]+\\s*['\"][^'\"\\s]{8,}['\"]"
356
- - "(?<![?&/])cookie\\s*[=:]+\\s*['\"][^'\"\\s]{8,}['\"]"
367
+ - "(?<![?&/])password(?![A-Za-z])\\w*\\s*[=:]+\\s*[a-zA-Z]{0,2}\\s*['\"][^'\"\\s]{8,}['\"]"
368
+ - "(?<![?&/])secret(?![A-Za-z])\\w*\\s*[=:]+\\s*[a-zA-Z]{0,2}\\s*['\"][^'\"\\s]{8,}['\"]"
369
+ - "(?<![?&/])api[_-]?key(?![A-Za-z])\\w*\\s*[=:]+\\s*[a-zA-Z]{0,2}\\s*['\"][^'\"\\s]{8,}['\"]"
370
+ - "(?<![?&/])token(?![A-Za-z])\\w*\\s*[=:]+\\s*[a-zA-Z]{0,2}\\s*['\"][^'\"\\s]{8,}['\"]"
371
+ - "(?<![?&/])cookie(?![A-Za-z])\\w*\\s*[=:]+\\s*[a-zA-Z]{0,2}\\s*['\"][^'\"\\s]{8,}['\"]"
357
372
  # 2026-09-13 误报修复:正则把「凭据字段引用/API 名/字符串字面量」误判为「凭据值硬编码」。
358
373
  # 白名单行豁免——命中以下任一模子的行不报:
359
374
  # · GM_cookie(油猴 GM_cookie API 名,非硬编码值)
@@ -22,7 +22,13 @@ rules:
22
22
  - id: paths/hardcoded-absolute-path
23
23
  name: "硬编码绝对路径(换机即失效)"
24
24
  category: "paths"
25
- severity: "warning"
25
+ # blocker:写死本机数据/资源目录会直接导致换机、换挂载点后功能失效(真实故障形态)。
26
+ # 为不误伤正确写法,精筛排除了两类(见 lib/checks/hardcoded-path.js::isReasonableAbsolutePath):
27
+ # ① 临时目录 /tmp /var/tmp /dev/shm(跨机语义一致)
28
+ # ② 系统工具目录 /usr/bin /usr/local/bin /var/packages…(多候选探测是 tool-self-detection
29
+ # 要求的正确做法,把它当硬编码拦等于逼项目只能依赖 PATH)
30
+ # 文档类文件仍降级为 warning(示例路径属说明内容,见 lib/checks/regex.js 的文档降级)。
31
+ severity: "blocker"
26
32
  description: "字符串里写死本机绝对路径(/volume1、/home、/Users、C:\\、\\\\server\\share、file://),换机/迁移/换挂载点后失效;应改为相对路径(基准 = 文件所在目录)、path.join 或配置项传入"
27
33
  patterns:
28
34
  - "/(volume[0-9]+|home|Users|var|usr|opt|tmp|mnt|srv|etc|root|Applications|Volumes)/[^\\s\"'`),;]+"
@@ -0,0 +1,117 @@
1
+ /**
2
+ * contract.js —— 审计 UI 契约:什么算一个可插拔的审计面板、缺什么算构建失败。
3
+ *
4
+ * 为什么契约单独成文件、并且只有常量 + 校验函数(照 dsh-model-team 的 ui/theme-sdk 范式):
5
+ * 面板实现是「别人写的代码」,它只应该依赖这一层。契约一旦散落到 SDK 各处,
6
+ * 作者就得靠读实现来猜哪些能用 —— 那等于没有契约。
7
+ * 校验发生在**构建期**(将来接回 UI 时由构建脚本调 defineAuditPanel),运行期不再重复校验:
8
+ * 坏实现应该在打包时被挡住,而不是等宿主里白屏才被发现。
9
+ *
10
+ * 校验项刻意只覆盖「构建期一定能判」的部分(形状与版本),**不猜作者意图**:
11
+ * 猜意图的校验(例如「Panel 是否真的渲染了 summary」「styles 里有没有外链 CSS」)
12
+ * 会在真实实现上误报,最后逼人把校验关掉 —— 那比没有校验更糟。
13
+ *
14
+ * 本文件零依赖(不 import 任何模块):它既要能进构建脚本,也要能进浏览器产物,
15
+ * 任何 Node 专有 API 都会让它两边都用不了。test/test-audit-ui-contract.mjs 钉住这条。
16
+ *
17
+ * 契约形状(与 docs/SPEC.md 第十一节同源):
18
+ * defineAuditPanel({ meta: { id, name, contractVersion }, Panel, styles?, setup? })
19
+ * Panel(props) 收到的 props 分三组,键名见下方三个常量:
20
+ * data —— 执行侧/宿主给的面板只读数据(summary / quality / findings / ruleSlots)
21
+ * actions —— 面板可以调的动作(reload / toggleRule / editWeight / toggleDisabled)
22
+ * state —— 宿主状态快照(loading / error / auditEnabled / auditScanScope)
23
+ * 数据只读、状态只读、要改状态走 actions —— 面板不自己保存这些状态。
24
+ */
25
+
26
+ /** 契约版本:SDK 的破坏性改动就 +1,构建期用它拒掉按旧契约写的实现。 */
27
+ export const AUDIT_UI_CONTRACT_VERSION = 1;
28
+
29
+ /** meta.id 的合法形状:小写字母开头 + [a-z0-9-],2~32 字符。
30
+ * 用做样式命名空间(写进 [data-audit-panel="id"]),所以必须是能当 CSS 属性值的形状。 */
31
+ export const AUDIT_PANEL_ID_PATTERN = /^[a-z][a-z0-9-]{1,31}$/;
32
+
33
+ /** 面板拿到的只读数据键(与引擎返回字段同名,不再做二次改名);导出成常量而非只写注释,
34
+ * 宿主与实现都从这里取键名,改名只改一处。 */
35
+ export const AUDIT_PANEL_DATA_KEYS = Object.freeze(['summary', 'quality', 'findings', 'ruleSlots']);
36
+
37
+ /** 面板可以调的动作(实现只读地拿到这些函数;要不要用是实现的自由)。 */
38
+ export const AUDIT_PANEL_ACTION_KEYS = Object.freeze(['reload', 'toggleRule', 'editWeight', 'toggleDisabled']);
39
+
40
+ /** 面板能看到的宿主状态(只读快照;面板自己不应保存这些状态)。 */
41
+ export const AUDIT_PANEL_STATE_KEYS = Object.freeze(['loading', 'error', 'auditEnabled', 'auditScanScope']);
42
+
43
+ /** meta 只认这三个字段:未登记的键不会带进产物(契约面就是这三个,不是"随便加")。 */
44
+ const META_KEYS = Object.freeze(['id', 'name', 'contractVersion']);
45
+
46
+ /**
47
+ * 校验 meta 三个字段。
48
+ * 每一项单独报错并带上字段名与要求 —— 契约可用性的一半在错误信息:
49
+ * 只说「meta 非法」会让人回去翻文档,说清「要求 /^[a-z][a-z0-9-]{1,31}$/」才修得动。
50
+ * @param {object} meta 面板定义的 meta
51
+ */
52
+ function assertMetaShape(meta) {
53
+ if (!meta || typeof meta !== 'object') {
54
+ throw new Error('[audit-ui] 缺少 meta(要求 { id, name, contractVersion })');
55
+ }
56
+ if (typeof meta.id !== 'string' || !AUDIT_PANEL_ID_PATTERN.test(meta.id)) {
57
+ throw new Error(`[audit-ui] meta.id 非法:${JSON.stringify(meta.id)}(要求 ${String(AUDIT_PANEL_ID_PATTERN)};小写字母开头、只含 [a-z0-9-]、2~32 字符)`);
58
+ }
59
+ if (typeof meta.name !== 'string' || meta.name.trim() === '') {
60
+ throw new Error(`[audit-ui] meta.name 必须是非空字符串(收到 ${JSON.stringify(meta.name)})`);
61
+ }
62
+ if (meta.contractVersion !== AUDIT_UI_CONTRACT_VERSION) {
63
+ throw new Error(`[audit-ui] meta.contractVersion 不匹配:面板写的是 ${JSON.stringify(meta.contractVersion)},当前 SDK 是 ${AUDIT_UI_CONTRACT_VERSION}(按旧契约写的实现要跟着改)`);
64
+ }
65
+ }
66
+
67
+ /**
68
+ * 校验必填项:Panel 必须是函数。
69
+ * 只判「是不是函数」——判不了「它渲染得对不对」,后者要跑起来才知道,属于运行期的事。
70
+ * @param {object} definition 面板定义
71
+ */
72
+ function assertRequiredParts(definition) {
73
+ if (typeof definition.Panel !== 'function') {
74
+ throw new Error(`[audit-ui] Panel 必须是函数组件(收到 ${typeof definition.Panel})`);
75
+ }
76
+ }
77
+
78
+ /**
79
+ * 校验可选项:出现即必须是约定类型(缺省 = 不启用该能力)。
80
+ * @param {object} definition 面板定义
81
+ */
82
+ function assertOptionalParts(definition) {
83
+ if (definition.styles !== undefined && typeof definition.styles !== 'string') {
84
+ throw new Error(`[audit-ui] styles 若存在必须是字符串(收到 ${typeof definition.styles};自带 CSS 文本,不要引外部 CSS 文件)`);
85
+ }
86
+ if (definition.setup !== undefined && typeof definition.setup !== 'function') {
87
+ throw new Error(`[audit-ui] setup 若存在必须是函数(收到 ${typeof definition.setup};返回值可作为卸载清理函数)`);
88
+ }
89
+ }
90
+
91
+ /**
92
+ * 声明并校验一个审计面板(构建期调用)。
93
+ *
94
+ * 返回值是**冻结的新对象**(只含契约内的字段):
95
+ * · 运行期有人往面板对象上挂字段 → 严格模式下直接抛错,而不是静默生效后被别处读到;
96
+ * · 未登记的字段不会被带进产物 —— 「契约面有哪几个字段」是确定的,不随作者顺手加键而膨胀。
97
+ *
98
+ * @param {object} definition { meta, Panel, styles?, setup? }
99
+ * @returns {{meta: object, Panel: Function, styles?: string, setup?: Function}} 冻结后的面板定义
100
+ */
101
+ export function defineAuditPanel(definition) {
102
+ if (!definition || typeof definition !== 'object' || Array.isArray(definition)) {
103
+ throw new Error('[audit-ui] defineAuditPanel 需要一个对象参数(形如 { meta, Panel, styles?, setup? })');
104
+ }
105
+ assertMetaShape(definition.meta);
106
+ assertRequiredParts(definition);
107
+ assertOptionalParts(definition);
108
+ // meta 只保留契约字段:多写的键不进产物,避免「产物里有、契约里没有」的暗面
109
+ const meta = {};
110
+ for (const key of META_KEYS) meta[key] = definition.meta[key];
111
+ return Object.freeze({
112
+ meta: Object.freeze(meta),
113
+ Panel: definition.Panel,
114
+ styles: definition.styles,
115
+ setup: definition.setup,
116
+ });
117
+ }
@@ -0,0 +1,17 @@
1
+ /**
2
+ * index.js —— 审计 UI SDK 的唯一导出面:面板实现只允许从这里 import。
3
+ *
4
+ * 为什么「只留一个入口」:分组导出看着只是方便,实际是**什么算稳定契约**的边界——
5
+ * 实现若绕过它去 import contract.js 的内部细节,SDK 一旦重构就会伤到别人。
6
+ * 所以本文件只 re-export 承诺面,一个多余符号都不加;想加符号先问「它算契约吗」。
7
+ * 契约形状(meta/Panel/styles/setup 与 props 三组键)的权威说明在 ./contract.js 头部。
8
+ */
9
+
10
+ export {
11
+ AUDIT_UI_CONTRACT_VERSION,
12
+ AUDIT_PANEL_ID_PATTERN,
13
+ AUDIT_PANEL_DATA_KEYS,
14
+ AUDIT_PANEL_ACTION_KEYS,
15
+ AUDIT_PANEL_STATE_KEYS,
16
+ defineAuditPanel,
17
+ } from './contract.js';
@@ -102,8 +102,8 @@ export function consoleLogJsonLines(text) {
102
102
  * @param {string} text 文件全文
103
103
  * @returns {Set<number>} 允许报的行号集合
104
104
  */
105
- export function shortFuncNameLines(text) {
106
- return new Set(checkShortFunctionNameAst(String(text || '')).map((h) => h.line));
105
+ export function shortFuncNameLines(text, tree) {
106
+ return new Set(checkShortFunctionNameAst(String(text || ''), { tree: tree || null }).map((h) => h.line));
107
107
  }
108
108
 
109
109
  /**
@@ -119,8 +119,8 @@ export function placeholderCredentialLines(text, file) {
119
119
  return checkPlaceholderCredentialAst(text, file);
120
120
  }
121
121
 
122
- export function credentialValueLines(text) {
123
- return checkCredentialRefAst(String(text || ''));
122
+ export function credentialValueLines(text, tree) {
123
+ return checkCredentialRefAst(String(text || ''), tree);
124
124
  }
125
125
 
126
126
  /**
@@ -24,6 +24,7 @@ import { checkPrivateFiles } from './private.js';
24
24
  import { checkButtonBindings } from './button-bind.js';
25
25
  import { checkMagicNumberSmart } from './magic-number.js';
26
26
  import { checkDataflow } from './dataflow.js';
27
+ import { checkScopeCollision } from './scope-collision.js';
27
28
  import { checkFileHealth } from './file-health.js';
28
29
  import { filterRulesByExt, filterRulesByPath, filterRulesByFileText } from './filter.js';
29
30
  import { resolveDshClientEntries, resolveDshClientFragments } from '../audit/client-entry.js';
@@ -103,6 +104,10 @@ export function runChecks({ file, relPath, text, grouped }, opts = {}) {
103
104
  // 三层审计 L2——数据流检查(kind=dataflow,如 clear-then-access 同函数清空后访问)
104
105
  // L1 已在 filterRulesByFileText 初筛:file_patterns 未命中的文件这里 grouped 已空,空规则短路
105
106
  if (!quick && grouped['dataflow']) findings = findings.concat(checkDataflow({ file, text, rules: grouped['dataflow'] }));
107
+ // 拼接产物作用域撞名(多段 JS 拼进同一作用域):判定在 lib/ast/scope-collisions.js,
108
+ // 契约由被审项目自己的 package.json 决定(lib/audit/scope-policy.js)——
109
+ // 规则 yml 跨仓库共享,故 yml 只声明「查不查」,不写任何项目的前缀约定。
110
+ if (!quick && grouped['scope-collision']) findings = findings.concat(checkScopeCollision({ file, text, rules: grouped['scope-collision'] }));
106
111
  findings = findings.concat(checkEmptyCatch({ file, text }));
107
112
  // I/O 风险分级 —— 经「正则初筛 → AST 精筛」产出(robustness/io-risk
108
113
  // 规则 + astConfirmKind: io-risk),不在此独立调用检查器:两条路径会为同一处 I/O
@@ -14,6 +14,7 @@
14
14
  * regex.js 正则类规则(含 astConfirm 精筛消费)
15
15
  * structural.js 结构类(函数长度/复杂度/嵌套/文件行数/同步 fs/空 catch)
16
16
  * semantic.js 语义类(yml 声明的语义检查、patch insert)
17
+ * scope-collision.js 拼接产物作用域撞名(多段 JS 共用同一作用域)
17
18
  * npm-json.js package.json 规范
18
19
  * folder.js 目录级检查
19
20
  * credential-file.js 凭据文件
@@ -42,6 +43,7 @@ export { checkButtonBindings } from './button-bind.js';
42
43
  export { checkMagicNumberSmart } from './magic-number.js';
43
44
  export { checkFileHealth } from './file-health.js';
44
45
  export { checkDataflow } from './dataflow.js';
46
+ export { checkScopeCollision } from './scope-collision.js';
45
47
  export { checkDuplicateCode } from './dup-code.js';
46
48
  export { checkMultiFileScanners } from './fs-scanner.js';
47
49
  export { checkDuplicateConst, findConstDefs } from './dup-const.js';
@@ -109,8 +109,8 @@ export function checkRegexRules({ file, text, rules, source = '新增行', repoP
109
109
  if (rule.astConfirmKind === 'small-file-read') kindFilter = { mode: 'deny', lines: smallFileReadLines(text) };
110
110
  // CLI console.log(JSON.stringify(大对象)) 一次性输出行豁免(memory-bomb json-stringify-large)
111
111
  else if (rule.astConfirmKind === 'console-log-json') kindFilter = { mode: 'deny', lines: consoleLogJsonLines(text) };
112
- else if (rule.astConfirmKind === 'short-func-name') kindFilter = { mode: 'allow', lines: shortFuncNameLines(text) };
113
- else if (rule.astConfirmKind === 'credential-value') kindFilter = { mode: 'allow', lines: credentialValueLines(text) };
112
+ else if (rule.astConfirmKind === 'short-func-name') kindFilter = { mode: 'allow', lines: shortFuncNameLines(text, treeConfirm?.tree || null) };
113
+ else if (rule.astConfirmKind === 'credential-value') kindFilter = { mode: 'allow', lines: credentialValueLines(text, treeConfirm?.tree || null) };
114
114
  // 前缀型密钥串(ghp_/sk-/AKIA)的占位符精筛:命中行是「演示值/占位文案」时豁免
115
115
  else if (rule.astConfirmKind === 'placeholder-credential') kindFilter = { mode: 'deny', lines: placeholderCredentialLines(text, file) };
116
116
  // shell 健壮性精筛(folder/cd-to-maybe-missing:cd 到动态路径且无兜底)
@@ -192,9 +192,14 @@ export function checkRegexRules({ file, text, rules, source = '新增行', repoP
192
192
  // 使「展示口径」与「计分口径」一致:info 即不计分)。
193
193
  const ioSev = rule.astConfirmKind === 'io-risk' && ioHit
194
194
  && (ioHit.risk === 'low' || ioHit.risk === 'safe') ? 'info' : null;
195
+ // 文档类文件降级:文档里写路径示例是**说明内容**,不是可执行代码里的坏路径。
196
+ // 规则本体是 blocker(拦真代码里的硬编码),文档统一降 warning 保留可见性。
197
+ const docDowngrade = rule.astConfirmKind === 'hardcoded-abs-path'
198
+ && (/\.(md|markdown|mdx|txt|rst|adoc)$/i.test(String(file || ''))
199
+ || /(^|\/)docs?\//i.test(String(file || ''))) ? 'warning' : null;
195
200
  findings.push(makeFinding({
196
201
  file, line: i + 1, rule: rule.id, kind: rule.kind,
197
- severity: ioSev || (rule.level === 'blocker' ? 'blocker' : rule.severity),
202
+ severity: ioSev || docDowngrade || (rule.level === 'blocker' ? 'blocker' : rule.severity),
198
203
  // I/O 分级 > 子模式专属 > 规则级
199
204
  message: ioMsg || hcMsg || subs?.[j]?.message || rule.message || rule.name,
200
205
  dimensions: rule.dimensions,
@@ -0,0 +1,68 @@
1
+ /**
2
+ * 检查层 · 拼接产物作用域撞名(kind = scope-collision)
3
+ *
4
+ * 判定在 `lib/ast/scope-collisions.js`(token 级、按真实作用域帧),契约在
5
+ * `lib/audit/scope-policy.js`(按**被审项目自己**的 package.json 取)。
6
+ *
7
+ * 两类命中,严重度口径**故意不同**:
8
+ * ① 同帧重名(任何 js 文件都查)——分两档,避免把合法写法拦成 blocker:
9
+ * · 两次都是 var:同一声明的重复写入(后一次等价赋值),运行时无害 → warning;
10
+ * · 含 function / class / const / let:后声明真的顶掉前者,或拼接后整份产物
11
+ * 直接 SyntaxError → 跟随规则声明(yml `severity: error` ⇒ blocker 拦截提交)。
12
+ * ② 前缀 / 顶层零声明(**只对项目自己声明的产物文件**生效)——契约类问题,
13
+ * 一律 capSeverity 到 warning:绝不因为别人的风格约定拦下提交。
14
+ *
15
+ * 为什么契约必须以「项目自己声明」为准:规则包是**跨仓库共享**的(同一份 yml 审计所有仓库)。
16
+ * 把 dshgp_ 写进 yml,会给所有被审项目刷出「缺少 dshgp_ 前缀」,
17
+ * 把真正的同帧重名淹掉。项目没声明 dshScopeCheck ⇒ 这里只做通用项(同帧重名)。
18
+ *
19
+ * 豁免:空 rules 短路(规则被 exts/exclude_paths/file_patterns 过滤空时,
20
+ * 防止读 rule.severity 抛错——与 structural.js 各检查器同款守卫)。
21
+ */
22
+
23
+ import { makeFinding } from '../audit/index.js';
24
+ import { readProjectScopePolicy } from '../audit/scope-policy.js';
25
+ import { analyzeScopeCollisions } from '../ast/index.js';
26
+ import { HINT_QUALITY, capSeverity } from './common.js';
27
+
28
+ /**
29
+ * @param {object} ctx { file(绝对路径), relPath, text, rules }
30
+ * @returns {Array} findings
31
+ */
32
+ export function checkScopeCollision({ file, text, rules }) {
33
+ const findings = [];
34
+ const rule = (rules || [])[0];
35
+ if (!rule) return findings;
36
+
37
+ const project = readProjectScopePolicy(file);
38
+ // 全仓扫描口径:必须严格命中项目声明的 files 清单,不能「没清单就都算产物」
39
+ const enforceContract = project.declared && project.isDeclaredArtifact;
40
+ const result = analyzeScopeCollisions(String(text || ''), {
41
+ prefix: enforceContract ? project.prefix : '',
42
+ allowlist: enforceContract ? project.allowlist : [],
43
+ topLevelMustBeEmpty: enforceContract ? project.topLevelMustBeEmpty : false,
44
+ });
45
+
46
+ const ruleId = rule.id || 'dsh/scope-collision';
47
+ const dimensions = rule.dimensions || ['健壮性'];
48
+ const base = { file, rule: ruleId, kind: 'scope-collision', dimensions, exemptHint: HINT_QUALITY, scoreImpact: 1 };
49
+ // 契约类(前缀 / 顶层零声明)与「纯 var 重声明」最高只到 warning
50
+ const softSeverity = capSeverity(rule.severity || 'warning', 'warning');
51
+ // ① 同帧重名:严重度按**命中性质**分档,避免把合法写法拦成 blocker
52
+ // · 两次都是 var ⇒ 同一声明的重复写入(后一次等价赋值),运行时无害 → warning
53
+ // · 含 function / class / const / let ⇒ 后声明真的顶掉前者,或拼接后整份产物
54
+ // 直接 SyntaxError(命名冲突)→ 按规则声明的严重度(error ⇒ blocker)
55
+ const hardSeverity = rule.level === 'blocker' ? 'blocker' : capSeverity(rule.severity || 'warning', 'warning');
56
+ for (const hit of result.duplicates) {
57
+ const varOnly = Array.isArray(hit.keywords) && hit.keywords.every((kw) => kw === 'var');
58
+ findings.push(makeFinding({ ...base, line: hit.line, severity: varOnly ? softSeverity : hardSeverity, message: hit.message }));
59
+ }
60
+ // ② 契约类(项目自选):恒为 warning
61
+ for (const hit of result.topLevel) {
62
+ findings.push(makeFinding({ ...base, line: hit.line, severity: softSeverity, message: hit.message }));
63
+ }
64
+ for (const hit of result.missingPrefix) {
65
+ findings.push(makeFinding({ ...base, line: hit.line, severity: softSeverity, message: hit.message }));
66
+ }
67
+ return findings;
68
+ }
@@ -8,11 +8,10 @@
8
8
  * 保持薄引用:审计逻辑在 lib/audit/*(与插件 code_audit 同源)。
9
9
  */
10
10
 
11
+ import { cliPluginConfig } from './shared.mjs';
11
12
  import { auditWithScope, auditFull } from '../audit/index.js';
12
13
  import { formatAnalysisCoverageLine } from '../audit/analysis-coverage.js';
13
14
  import { scoreQuality } from '../score/index.js';
14
- import { readSettings, applySettingsToCfg } from '../app/settings-bridge.js';
15
- import { defaultConfig } from '../client/index.js';
16
15
  import { access } from 'node:fs/promises';
17
16
  import { join } from 'node:path';
18
17
  import { probeRepoOwnership } from '../app/repo-ownership.js';
@@ -20,21 +19,9 @@ import { probeRepoOwnership } from '../app/repo-ownership.js';
20
19
  /** 审计 full 扫描 findings 打印条数上限(防刷屏)。 */
21
20
  const AUDIT_PRINT_LIMIT = 20;
22
21
 
23
- /** 读插件同一份配置(config.json)→ 运行期 cfg(与插件启动回读同一映射)。
24
- * 注意:applySettingsToCfg 是**原地修改** cfg、返回 { changedSystemPrompt } 状态对象
25
- * (与插件 apply.js 用法一致:`const changed = applySettingsToCfg(cfg, saved)`)。
26
- * 绝不能把它的返回值当 cfg 用——那会让 auditLevel/maxScanFiles/weightOverrides 等全变
27
- * undefined,CLI 结果与插件不一致。 */
28
- export function cliPluginConfig() {
29
- const cfg = defaultConfig();
30
- try {
31
- const saved = readSettings({});
32
- applySettingsToCfg(cfg, saved || {}); // 原地改 cfg,忽略返回值
33
- } catch {
34
- /* 配置缺失/损坏 → 保留 defaultConfig(与插件首启一致) */
35
- }
36
- return cfg;
37
- }
22
+ // cliPluginConfig 已挪到 lib/cli/shared.mjs(三入口共用;git 侧读配置不必 import 审计实现)。
23
+ // 这里保留同名导出,外部按老路径 import 不受影响。
24
+ export { cliPluginConfig };
38
25
 
39
26
  /**
40
27
  * 构造与插件 code_audit **完全相同**的审计参数(保证 CLI 与插件结果一致)。
@@ -101,7 +88,7 @@ async function runStandardAudit(root, flags) {
101
88
  opts.ownership = probeRepoOwnership(root); // 与插件工具同参:隐私规则只对自有仓库生效
102
89
  const weights = pluginEqualWeights(cfg, flags);
103
90
  const auditResult = full ? await auditFull(root, opts) : await auditWithScope(root, opts);
104
- const quality = scoreQuality(auditResult.findings, weights, { files: auditResult.files, dimFileCounts: auditResult.dimFileCounts });
91
+ const quality = scoreQuality(auditResult.findings, weights, { files: auditResult.files, dimFileCounts: auditResult.dimFileCounts, dimRuleCounts: auditResult.dimRuleCounts });
105
92
  if (flags.json) {
106
93
  console.log(JSON.stringify({ ok: true, repo: root, scope: auditResult.scope, summary: auditResult.summary, quality, findings: auditResult.findings, files: auditResult.files, analysisCoverage: auditResult.analysisCoverage || null, yaml: auditResult.yaml }, null, 2));
107
94
  return;
@@ -136,6 +123,14 @@ function printAuditResult(root, auditResult, opts, weights, quality) {
136
123
  * (实测「CLI 全量扫描分更低、文件更多」:跑了已禁用规则包 + 默认权重 + 不同文件上限)。
137
124
  * 现在 CLI 读**同一份** config.json($DSH_HOME/git-push/config.json),用与插件 code_audit
138
125
  * 完全相同的 auditOpts 与入口(auditFull),保证功能与结果一致。 */
126
+ /**
127
+ * ⚠️ **当前 CLI 不可达**(2026-11-13 核实):`scan` 命令由注册表 `git_scan` 接管
128
+ * (输出 `count: N` 的仓库扫描),本函数不挂在任何 COMMANDS 表里。
129
+ * 保留原因:它调的是 `auditWithScope(root,{scope:'full',depth})`,是「按审计口径扫描」的
130
+ * 另一种语义,将来若要提供 `scan --audit` 之类可复用。**注意它没传**
131
+ * `maxScanFiles / disabledSlots / rulesetDir` —— 若接回 CLI,需先补这三个,
132
+ * 否则会与插件侧的扫描口径不一致。
133
+ */
139
134
  export async function cmdScan(root, flags) {
140
135
  const depth = flags.depth ?? 3;
141
136
  const scanResult = await auditWithScope(root, { scope: 'full', depth });
@@ -0,0 +1,93 @@
1
+ // CLI 工具链域命令实现(tool-sluice 独占)
2
+ //
3
+ // 为什么单独成文件:这三个命令是「对项目自身/脚手架的检查与模板输出」,与 git 操作、
4
+ // 审计执行都无关;放在入口文件里会让 tool-sluice 的入口从薄壳变成半个实现。
5
+ //
6
+ // self-check 的职责(拆分后比原来更重要):三个入口各有一份 HELP + KNOWN_FLAGS,
7
+ // 任何一份写歪都会让用户按 HELP 抄命令失败。它逐个入口比对「HELP 里写的 flag」与
8
+ // 「该入口 parseArgv 认的 flag」,并核对每个入口的 HELP 是否列出自己全部命令。
9
+
10
+ import { VERSION, helpSync, readmeTemplate, yamlTemplate } from '../self/index.js';
11
+ import { readFileSync } from 'node:fs';
12
+
13
+ import { CLI_ENTRIES, allCommands, parseEntrySourceMeta, readEntrySource } from './shared.mjs';
14
+
15
+ /** 入口文件清单(bin → 源文件)。自检逐个核对。 */
16
+ export const ENTRY_FILES = [
17
+ { cliName: 'git-sluice', file: 'cli.mjs' },
18
+ { cliName: 'audit-sluice', file: 'cli-audit.mjs' },
19
+ { cliName: 'tool-sluice', file: 'cli-tool.mjs' },
20
+ ];
21
+
22
+ /** 读 package.json(失败返回 null)。 */
23
+ export function readPkgJson() {
24
+ try {
25
+ return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
26
+ } catch { return null; }
27
+ }
28
+
29
+ /** 子命令:yaml-template — 输出规则 yml 模板。 */
30
+ export function cmdYamlTemplate() {
31
+ console.log(yamlTemplate());
32
+ }
33
+
34
+ /** 子命令:readme-template — 输出 README 模板。 */
35
+ export function cmdReadmeTemplate() {
36
+ console.log(readmeTemplate().template);
37
+ }
38
+
39
+ /**
40
+ * 逐个入口核对「HELP ↔ parseArgv」与「HELP 是否列出本侧全部命令」。
41
+ * @returns {{failures: string[], lines: string[]}}
42
+ */
43
+ export function checkEntries() {
44
+ const failures = [];
45
+ const lines = [];
46
+ for (const { cliName, file } of ENTRY_FILES) {
47
+ let meta;
48
+ try {
49
+ meta = parseEntrySourceMeta(readEntrySource(file));
50
+ } catch (e) {
51
+ failures.push(`${file}: 读取失败(${e.message})`);
52
+ continue;
53
+ }
54
+ if (!meta.help) { failures.push(`${file}: 未找到 HELP 常量`); continue; }
55
+ const sync = helpSync(meta.help, meta.flags);
56
+ if (!sync.ok) {
57
+ failures.push(`${file}: HELP 与 KNOWN_FLAGS 不一致`);
58
+ for (const missingFlag of sync.missingInHelp) failures.push(` ${file}: KNOWN_FLAGS 有但 HELP 没写 ${missingFlag}`);
59
+ for (const extraFlag of sync.missingInParse) failures.push(` ${file}: HELP 写了但 KNOWN_FLAGS 没有 ${extraFlag}`);
60
+ continue;
61
+ }
62
+ // HELP 必须列出本侧每个命令的用法行(`<cli> <cmd>` 形式);缺了说明「加了命令忘了文档」
63
+ const missingCommands = (CLI_ENTRIES[cliName]?.commands || []).filter((cmd) => !meta.help.includes(`${cliName} ${cmd}`));
64
+ if (missingCommands.length) {
65
+ failures.push(`${file}: HELP 缺命令用法行 ${missingCommands.join(' ')}`);
66
+ } else {
67
+ lines.push(` ✓ ${file}: HELP↔KNOWN_FLAGS 一致(${meta.flags.length} 个 flag)· 本侧 ${(CLI_ENTRIES[cliName]?.commands || []).length} 个命令都有用法行`);
68
+ }
69
+ }
70
+ return { failures, lines };
71
+ }
72
+
73
+ /** 子命令:self-check — 版本一致性 + 三入口 HELP↔parseArgv 机器比对 + 命令覆盖。 */
74
+ export function cmdSelfCheck() {
75
+ const failures = [];
76
+ console.log('自身自检:');
77
+ console.log(` version: v${VERSION}`);
78
+ const pkg = readPkgJson();
79
+ if (pkg && pkg.version && pkg.version !== VERSION) {
80
+ failures.push(`version: lib/self=${VERSION} vs package.json=${pkg.version}`);
81
+ console.error(` ✗ version: lib/self=${VERSION} vs package.json=${pkg.version}`);
82
+ } else {
83
+ console.log(` ✓ version: lib/self = package.json = ${VERSION}`);
84
+ }
85
+ const { failures: entryFailures, lines } = checkEntries();
86
+ for (const reportLine of lines) console.log(reportLine);
87
+ // 一次性并入(不在循环里逐条 push:既少一层循环,也让「失败清单来自一处」更好读)
88
+ failures.push(...entryFailures);
89
+ for (const failure of entryFailures) console.error(` ✗ ${failure}`);
90
+ if (!entryFailures.length) console.log(` ✓ 命令覆盖:三入口共 ${allCommands().length} 个命令都有用法行`);
91
+ process.exitCode = failures.length > 0 ? 1 : 0;
92
+ return failures.length > 0 ? 1 : 0;
93
+ }