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.
Files changed (239) hide show
  1. package/README.md +76 -47
  2. package/cli-tool.mjs +2 -4
  3. package/cli.mjs +11 -4
  4. package/lib/app/apply.js +15 -13
  5. package/lib/app/command-registry.js +26 -19
  6. package/lib/app/handlers/http-constants.js +8 -0
  7. package/lib/app/handlers/meta.js +2 -2
  8. package/lib/app/handlers/preprocess.js +104 -0
  9. package/lib/app/handlers/repo-actions.js +2 -3
  10. package/lib/app/handlers/repos.js +137 -10
  11. package/lib/app/handlers/settings.js +34 -15
  12. package/lib/app/http-handlers.js +13 -42
  13. package/lib/app/index.js +3 -2
  14. package/lib/app/inject-text.js +6 -21
  15. package/lib/app/preprocess-client.js +136 -0
  16. package/lib/app/repo-ownership.js +1 -1
  17. package/lib/app/schema.js +20 -10
  18. package/lib/app/settings-bridge.js +60 -8
  19. package/lib/app/severity.js +14 -0
  20. package/lib/app/slash-commands.js +5 -164
  21. package/lib/app/tool-call.js +96 -163
  22. package/lib/cli/commands-preprocess.mjs +74 -0
  23. package/lib/cli/commands-tool.mjs +3 -2
  24. package/lib/cli/commands-vcs.mjs +39 -5
  25. package/lib/cli/shared.mjs +36 -10
  26. package/lib/client/index.js +11 -16
  27. package/lib/client-parts/git/account.js +21 -12
  28. package/lib/client-parts/git/actions.js +23 -77
  29. package/lib/client-parts/git/apply.js +8 -2
  30. package/lib/client-parts/git/browser.js +1 -1
  31. package/lib/client-parts/git/const.js +33 -1
  32. package/lib/client-parts/git/controller.js +175 -176
  33. package/lib/client-parts/git/icons.js +1 -1
  34. package/lib/client-parts/git/loader.js +1 -1
  35. package/lib/client-parts/git/npm.js +56 -37
  36. package/lib/client-parts/git/page.js +53 -1
  37. package/lib/client-parts/git/repo.js +8 -1
  38. package/lib/client-parts/git/settings.js +13 -1
  39. package/lib/client-parts/git/state.js +237 -0
  40. package/lib/client-parts/git/utils.js +1 -1
  41. package/lib/client.js +631 -312
  42. package/lib/commit-push/pre-commit-engine.js +629 -30
  43. package/lib/commit-push.js +127 -67
  44. package/lib/context/index.js +7 -5
  45. package/lib/core/config.js +1 -27
  46. package/lib/core/exec.js +2 -11
  47. package/lib/{exempt/index.js → git/exempt-markers.js} +8 -1
  48. package/lib/git/identity-rewrite.js +1 -1
  49. package/lib/git/ignore.js +1 -1
  50. package/lib/git/index.js +1 -1
  51. package/lib/git/push.js +2 -17
  52. package/lib/git/repo-index.js +8 -3
  53. package/lib/git/repos.js +2 -2
  54. package/lib/git/sensitive.js +1 -1
  55. package/lib/npm/install.js +1 -1
  56. package/lib/npm/publish.js +20 -5
  57. package/lib/npm/registry.js +2 -2
  58. package/lib/plugin/auto-push.js +5 -8
  59. package/lib/preprocess/providers.js +195 -0
  60. package/lib/self/index.js +1 -1
  61. package/lib/skip-dirs.js +14 -55
  62. package/package.json +31 -42
  63. package/skills/dev/dsh-git-push.md +9 -9
  64. package/skills/guide/guide-commit-push.md +11 -13
  65. package/skills/workflow/README.md +0 -1
  66. package/skills/workflow/task-completion-report.md +2 -2
  67. package/.auditignore +0 -30
  68. package/.gitignore +0 -43
  69. package/cli-audit.mjs +0 -141
  70. package/lib/BUGFIX-NOTES-2026-09-14.md +0 -278
  71. package/lib/app/audit-api.js +0 -173
  72. package/lib/app/handlers/audit.js +0 -150
  73. package/lib/app/host-doc-checks.js +0 -25
  74. package/lib/app/schema-audit.js +0 -42
  75. package/lib/app/scope-check.js +0 -69
  76. package/lib/ast/brace.js +0 -120
  77. package/lib/ast/callgraph.js +0 -135
  78. package/lib/ast/code-lines.js +0 -175
  79. package/lib/ast/consts.js +0 -12
  80. package/lib/ast/control-flow.js +0 -470
  81. package/lib/ast/credential.js +0 -315
  82. package/lib/ast/dataflow.js +0 -391
  83. package/lib/ast/dup-code.js +0 -165
  84. package/lib/ast/fs-hotspots.js +0 -154
  85. package/lib/ast/index.js +0 -38
  86. package/lib/ast/io-risk-const.js +0 -95
  87. package/lib/ast/io-risk-fn.js +0 -208
  88. package/lib/ast/io-risk-loop.js +0 -308
  89. package/lib/ast/io-risk.js +0 -314
  90. package/lib/ast/lang.js +0 -156
  91. package/lib/ast/line-count.js +0 -52
  92. package/lib/ast/magic-number.js +0 -272
  93. package/lib/ast/naming.js +0 -292
  94. package/lib/ast/perf.js +0 -488
  95. package/lib/ast/scope-collisions.js +0 -228
  96. package/lib/ast/scope.js +0 -241
  97. package/lib/ast/shell.js +0 -131
  98. package/lib/ast/size.js +0 -448
  99. package/lib/ast/symbol-index.js +0 -399
  100. package/lib/ast/tokenizer.js +0 -421
  101. package/lib/ast/treesitter.js +0 -413
  102. package/lib/audit/analysis-coverage.js +0 -98
  103. package/lib/audit/audit-file.js +0 -205
  104. package/lib/audit/auditignore-rules.js +0 -148
  105. package/lib/audit/checks.js +0 -17
  106. package/lib/audit/client-entry.js +0 -93
  107. package/lib/audit/collector.js +0 -610
  108. package/lib/audit/ext-runner.js +0 -80
  109. package/lib/audit/file-context.js +0 -391
  110. package/lib/audit/finding.js +0 -101
  111. package/lib/audit/gitignore-match.js +0 -113
  112. package/lib/audit/glob.js +0 -63
  113. package/lib/audit/history-report.js +0 -100
  114. package/lib/audit/history.js +0 -126
  115. package/lib/audit/ignore-blind.js +0 -102
  116. package/lib/audit/index.js +0 -33
  117. package/lib/audit/orchestrate.js +0 -672
  118. package/lib/audit/public.js +0 -24
  119. package/lib/audit/repo-level.js +0 -30
  120. package/lib/audit/report-yaml.js +0 -90
  121. package/lib/audit/scope-policy.js +0 -110
  122. package/lib/audit/slot.js +0 -66
  123. package/lib/audit-rules/audit-rules-comment.yml +0 -199
  124. package/lib/audit-rules/audit-rules-cpp.yml +0 -114
  125. package/lib/audit-rules/audit-rules-csharp.yml +0 -82
  126. package/lib/audit-rules/audit-rules-docs.yml +0 -32
  127. package/lib/audit-rules/audit-rules-dsh.yml +0 -177
  128. package/lib/audit-rules/audit-rules-filehealth.yml +0 -42
  129. package/lib/audit-rules/audit-rules-folder.yml +0 -99
  130. package/lib/audit-rules/audit-rules-frontend.yml +0 -335
  131. package/lib/audit-rules/audit-rules-go.yml +0 -103
  132. package/lib/audit-rules/audit-rules-i18n.yml +0 -45
  133. package/lib/audit-rules/audit-rules-java.yml +0 -105
  134. package/lib/audit-rules/audit-rules-nodejs.yml +0 -662
  135. package/lib/audit-rules/audit-rules-npm.yml +0 -187
  136. package/lib/audit-rules/audit-rules-paths.yml +0 -98
  137. package/lib/audit-rules/audit-rules-performance.yml +0 -245
  138. package/lib/audit-rules/audit-rules-php.yml +0 -101
  139. package/lib/audit-rules/audit-rules-private.yml +0 -24
  140. package/lib/audit-rules/audit-rules-python.yml +0 -106
  141. package/lib/audit-rules/audit-rules-robustness.yml +0 -31
  142. package/lib/audit-rules/audit-rules-rust.yml +0 -109
  143. package/lib/audit-rules/audit-rules-structure.yml +0 -158
  144. package/lib/audit-rules/audit-rules-swift.yml +0 -99
  145. package/lib/audit-rules/audit-rules-template.yml +0 -108
  146. package/lib/audit-ui-sdk/contract.js +0 -117
  147. package/lib/audit-ui-sdk/index.js +0 -17
  148. package/lib/checks/button-bind.js +0 -347
  149. package/lib/checks/common.js +0 -170
  150. package/lib/checks/credential-file.js +0 -43
  151. package/lib/checks/dataflow.js +0 -40
  152. package/lib/checks/dispatch.js +0 -117
  153. package/lib/checks/dup-code.js +0 -69
  154. package/lib/checks/dup-const.js +0 -232
  155. package/lib/checks/file-health.js +0 -150
  156. package/lib/checks/filter.js +0 -137
  157. package/lib/checks/folder.js +0 -173
  158. package/lib/checks/fs-scanner.js +0 -57
  159. package/lib/checks/hardcoded-path.js +0 -98
  160. package/lib/checks/index.js +0 -49
  161. package/lib/checks/io.js +0 -66
  162. package/lib/checks/magic-number.js +0 -42
  163. package/lib/checks/npm-json.js +0 -273
  164. package/lib/checks/private.js +0 -64
  165. package/lib/checks/regex.js +0 -298
  166. package/lib/checks/scope-collision.js +0 -68
  167. package/lib/checks/semantic.js +0 -134
  168. package/lib/checks/structural.js +0 -281
  169. package/lib/cli/commands-audit.mjs +0 -142
  170. package/lib/cli/commands-doc.mjs +0 -127
  171. package/lib/client-parts/audit/audit.js +0 -301
  172. package/lib/exempt/tool.js +0 -198
  173. package/lib/git/module-splitter.js +0 -47
  174. package/lib/link-check/index.js +0 -187
  175. package/lib/lint-adapter/detect.js +0 -161
  176. package/lib/lint-adapter/index.js +0 -50
  177. package/lib/lint-adapter/runner.js +0 -133
  178. package/lib/preprocess/audit.js +0 -98
  179. package/lib/preprocess/index.js +0 -78
  180. package/lib/rule/compilers/credential.js +0 -62
  181. package/lib/rule/compilers/dataflow.js +0 -38
  182. package/lib/rule/compilers/file-health.js +0 -75
  183. package/lib/rule/compilers/frontend.js +0 -86
  184. package/lib/rule/compilers/func.js +0 -35
  185. package/lib/rule/compilers/helpers.js +0 -71
  186. package/lib/rule/compilers/index.js +0 -29
  187. package/lib/rule/compilers/link-semantic.js +0 -45
  188. package/lib/rule/compilers/list-kinds.js +0 -12
  189. package/lib/rule/compilers/numeric-kinds.js +0 -73
  190. package/lib/rule/compilers/regex.js +0 -78
  191. package/lib/rule/compilers/structure.js +0 -107
  192. package/lib/rule/compilers.js +0 -17
  193. package/lib/rule/homoglyph.js +0 -45
  194. package/lib/rule/loader.js +0 -274
  195. package/lib/rule/registry.js +0 -122
  196. package/lib/rule/scope.js +0 -67
  197. package/lib/score/docs-score.js +0 -166
  198. package/lib/score/index.js +0 -234
  199. package/lib/user-requirements.json +0 -15
  200. package/scripts/__pycache__/module-splitter.cpython-38.pyc +0 -0
  201. package/scripts/audit-ext/_example-readme-present.mjs +0 -34
  202. package/scripts/audit-ext/dsh-inject-declarations.mjs +0 -209
  203. package/scripts/audit-ext/variable-min-length.mjs +0 -102
  204. package/scripts/audit-gate.mjs +0 -235
  205. package/scripts/audit-runner.mjs +0 -35
  206. package/scripts/audit-runtime-check.mjs +0 -129
  207. package/scripts/browser-page-probe.mjs +0 -271
  208. package/scripts/build-client.mjs +0 -131
  209. package/scripts/bump-version.mjs +0 -178
  210. package/scripts/check-js-scope.mjs +0 -87
  211. package/scripts/check.mjs +0 -203
  212. package/scripts/clean-date-comments.py +0 -102
  213. package/scripts/cpu-sample.mjs +0 -188
  214. package/scripts/doc-drift.mjs +0 -200
  215. package/scripts/doc-func.mjs +0 -212
  216. package/scripts/doc-tree.mjs +0 -458
  217. package/scripts/doc-version.mjs +0 -149
  218. package/scripts/hot-path-probe-cjs.cjs +0 -71
  219. package/scripts/hot-path-probe-fs-shim.mjs +0 -28
  220. package/scripts/hot-path-probe-fsp-shim.mjs +0 -31
  221. package/scripts/hot-path-probe.mjs +0 -153
  222. package/scripts/local-registry.mjs +0 -37
  223. package/scripts/module-splitter.py +0 -800
  224. package/scripts/picker-repro.mjs +0 -115
  225. package/scripts/platform-scan.mjs +0 -168
  226. package/scripts/probe-recheck.mjs +0 -47
  227. package/scripts/rename-locator.mjs +0 -97
  228. package/scripts/rule-switch.mjs +0 -97
  229. package/scripts/rules-solo-audit.mjs +0 -173
  230. package/scripts/scan-file-io.mjs +0 -717
  231. package/scripts/scan-fs-hotspots.mjs +0 -107
  232. package/scripts/scan-version.mjs +0 -125
  233. package/scripts/symbol-index.mjs +0 -85
  234. package/scripts/verify-prestep.mjs +0 -100
  235. package/scripts/version-source.mjs +0 -173
  236. package/skills/dev/audit-rule-authoring.md +0 -58
  237. package/skills/guide/guide-audit.md +0 -270
  238. /package/lib/{audit → app}/ownership.js +0 -0
  239. /package/lib/{audit-defaults.js → git/defaults.js} +0 -0
@@ -1,270 +0,0 @@
1
- ---
2
- name: guide-audit
3
- description: dsh-git-push 代码审计:三个入口、审计范围、10 维度评分、规则包槽位、豁免机制、严重级与报告聚合,以及低成本整改(提取公共函数一次动作多规则清零)。处理代码审计/质量评分/整改提分类请求时加载。
4
- whenToUse: 要审计仓库、看质量分与问题明细、加停审计规则、豁免误报、查审计 API 时;要把审计分从 B 提到 A、低成本消 warning、规划重构整改时。
5
- updated: 2026-10-18
6
- generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
7
- ---
8
-
9
- # 代码审计(guide-audit)
10
-
11
- > 三条入口(工具 / HTTP API / CLI)跑同一套「静态初筛 + AST 语义审计」,输出 10 维度质量分与问题明细。
12
-
13
- ## 一、规则(场景 → 必须做的)
14
-
15
- | 场景 | 必须做的 |
16
- |---|---|
17
- | 要审计一个仓库 | 会话内用工具 `code_audit`;只看聚合明细用 HTTP `/api/git-push/audit`;脱离 DSH 用 `audit-sluice audit` |
18
- | 判断能否提交 | 门禁只认 `blocker`,命中即拦;`warning` / `notice` 只提示不拦 |
19
- | 遇到误报 | 先按判定类型选已有豁免机制;结构性误报优先修审计判定,不靠注释掩盖 |
20
- | 新增 / 停用规则 | 只改规则 yml(放文件即生效、删文件即移除),不改代码 |
21
- | 私有仓库 | 远端可见性 `private` 时审计只报告不拦截;`public` / `unknown` 保守拦截 |
22
-
23
- ## 二、怎么做 / 命令 / 实例
24
-
25
- ### 1. 三个入口(同一套引擎,结果一致)
26
-
27
- | 入口 | 调用方式 | 特点 |
28
- |---|---|---|
29
- | 工具 | `code_audit` | 默认精简输出(评分 / 各级数量 / 豁免统计 / API 指引);`includeFindings=true` 出全量 |
30
- | HTTP | `GET/POST /api/git-push/audit` | 请求时聚合:分组 / 严重级过滤 / 条数截断;默认全量范围 |
31
- | CLI | `audit-sluice audit <目录>` | 独立运行(零第三方依赖,Node ≥18 + 本机 git),`--json` 出全量 |
32
-
33
- ### 2. 工具 `code_audit` 参数
34
-
35
- | 参数 | 类型 | 必填 | 说明 |
36
- |---|---|---|---|
37
- | `repo` | string | ✅ | 仓库根目录 |
38
- | `scope` | string | — | `full`(全量)/ `diff`(变动范围);不传按变动范围;非 git 目录自动全量 |
39
- | `rulesetDir` | string | — | 自定规则目录 |
40
- | `includeIgnored` | boolean | — | 连 `.gitignore` 忽略的文件也扫 |
41
- | `includeFindings` | boolean | — | `true` 追加全量 `findings` 与 `yaml` |
42
- | `history` | boolean | — | 历史提交审计(逐提交快照全量审计并落盘报告) |
43
- | `since` / `until` / `outDir` | string | — | history 起止提交(皆缺省 = 全部历史,含两端)/ 报告目录(缺省 `<仓库>/audit-history/`) |
44
-
45
- 返回字段:`ok`、`scope`、`files`、`summary{blocker,warning,notice,total}`、`quality{score,level}`、`exemptStats{types,total}`、`blocked[]`(blocker 明细)、`groupByTypes`、`slotStats`、`apiGuide`;`includeFindings=true` 追加 `findings` + `yaml`。
46
- `history=true` 返回 `async:true` + `jobId`(宿主后台 job,完成自动回传)或 `result`(无 job 控制器时同步降级)。
47
-
48
- ### 3. HTTP 审计 API
49
-
50
- `GET/POST /api/git-push/audit`(参数放 query 或 JSON body,body 覆盖 query)。
51
-
52
- | 参数 | 默认 | 说明 |
53
- |---|---|---|
54
- | `repo` | 配置的默认扫描根 | 缺省且推断不出 → 400 `REPO_REQUIRED` |
55
- | `scope` | `full` | `full` / `diff` |
56
- | `groupBy` | `rule` | 聚合维度:`rule` / `file` / `severity` / `slot`(非法值回落 `rule`) |
57
- | `severity` | 不过滤 | 逗号白名单,如 `blocker,warning` |
58
- | `top` | `0` | 每组最多列前 N 条,`0` = 全部 |
59
- | `withFindings` / `withYaml` | `false` | `true` 时附全量 `findings` / `yaml` 报告 |
60
- | `includeIgnored` / `rulesetDir` / `maxScanFiles` / `weights` | — | 同工具 / CLI 语义(`includeIgnored` 连忽略文件也扫、`weights` 覆盖权重) |
61
-
62
- 返回:`ok`、`repo`、`scope`、`files`、`summary`、`quality{score,level}`、`groups[]`(按条数降序,每组含一条 `sample`)、`total`、`filtered`、`exemptStats`、`groupByTypes`、`blocked[]`。
63
-
64
- ### 4. CLI(`audit-sluice audit`)
65
-
66
- ```bash
67
- audit-sluice audit . # 变动范围(非 git 目录自动全量)
68
- audit-sluice audit . --full # 全量
69
- audit-sluice audit . --ruleset <规则目录> # 自定规则目录
70
- audit-sluice audit . --weights '{"安全性":25}' # 权重覆盖 JSON
71
- audit-sluice audit . --include-ignored # 连 .gitignore 忽略的文件也扫
72
- audit-sluice audit . --json # 全量 findings + yaml
73
- audit-sluice audit . --history --since <提交> --until <提交> --out <目录>
74
- ```
75
-
76
- CLI 读与插件同一份配置(`$DSH_HOME/git-push/config.json`);权重优先级:显式 `--weights` > 配置 `weightOverrides` > 默认权重表。CLI 与插件用同一实现、同一配置,同一仓库同一参数结果一致。
77
-
78
- ### 5. 审计范围(full / changed / diff)
79
-
80
- | 叫法 | 含义 |
81
- |---|---|
82
- | `full` | 全量扫描(非 git 目录也能查) |
83
- | `diff` / `changed` | 变动范围(未提交改动);`diff` 是入口写法,内部 scope 记为 `changed`,同一实现 |
84
-
85
- 默认范围:提交前自动审计取配置 `auditScanScope`(默认 `diff`);工具不传 `scope` 按变动范围;HTTP 不传按 `full`;CLI 默认变动范围。每次审计都跑完整流程(静态初筛 + AST 语义检查),没有可调强度档位。
86
-
87
- ### 6. 规则包与槽位
88
-
89
- - 规则目录里每个 `audit-rules-<名>.yml` = 一个槽位:放文件即生效、删文件即移除;yml 顶层 `disabled: true` = 整槽位默认不加载,`template` 槽位默认不加载。
90
- - `nodejs` / `private` 是安全红线强制槽位,不可禁用。
91
- - 启停方式:侧边栏「审计」选项卡规则包开关;HTTP `POST /api/git-push/toggle-rule`(body `{slot, disabled}`);脚本 `node scripts/rule-switch.mjs list|status|disable|enable <槽位>`(默认改安装版本,`--workspace` 指工作区,`--target <目录>` 任意指定)。
92
- - 规则装载每次审计实时读 yml,改完立即生效、无需重启实例;规则可声明 `astConfirmKind`:正则初筛拿候选行 → AST 语义确认,减少误报。
93
-
94
- ### 7. 10 维度质量评分
95
-
96
- | 维度 | 可读性 | 可维护性 | 健壮性 | 安全性 | 性能 | 测试覆盖 | 可观测性 | 可部署性 | 文档 | 开发者体验 |
97
- |---|---|---|---|---|---|---|---|---|---|---|
98
- | 默认权重 | 15 | 15 | 15 | 18 | 10 | 10 | 5 | 5 | 4 | 3 |
99
-
100
- - 单维度:`max(0.1, 10 - k×ln(1+问题数))`,k 按维度分级(安全性衰减最快),下限 0.1 防零分塌陷。
101
- - 总分:`Σ(维度分×权重)/Σ权重×10`,保留一位小数;等级 A ≥ 85、B ≥ 70、C ≥ 55、D ≥ 40,其余 E。
102
- - 权重可调:侧边栏 `weightOverrides`(JSON)/ HTTP `weights` / CLI `--weights`;`scoreImpact: 0` 的纯提醒不计入评分,0 文件不评分。
103
-
104
- ### 8. 严重级(severity)与评分影响
105
-
106
- | severity | 含义 | 门禁行为 |
107
- |---|---|---|
108
- | `blocker` | 拦截级(`error` 归一为 blocker) | 拦截提交;private 仓库只报告不拦 |
109
- | `warning` | 警告级 | 只提示 |
110
- | `notice` | 提示级(`info` 归一为 notice) | 只提示 |
111
-
112
- `scoreImpact` = 单条问题对评分的影响:`0` 纯提醒不扣分、`1` 常规、`2` 高危(如 blocker 凭据类);`summary` 汇总为 `{blocker, warning, notice, total}`。
113
-
114
- ### 9. 豁免机制
115
-
116
- | 机制 | 位置 / 写法 | 效果 |
117
- |---|---|---|
118
- | `.auditignore` | 仓库根,gitignore 语法 | 仓库级:声明不审计但照常入库;与 `.gitignore` 独立叠加;非 git 目录同样生效;`!` 前缀恢复 |
119
- | `dsh-skip-*` 文件头注释 | 前 3 行内注释 | 整文件豁免对应拦截类型 |
120
- | `dsh-skip-*` 行尾注释 | 对应行 / 函数定义行 | 单点豁免(仅 `sensitive` / `residue` / `func-length` / `complexity` / `i18n` 支持行级) |
121
- | `.test` / `.samples` 空文件 | 目录内放 0 字节标记文件 | `.test` = 该目录(含子目录)整棵跳过扫描、不出任何结果;`.samples` = 照常出结果但不拦截(示例目录豁免) |
122
- | 路径类别 | `test/`、`scripts/`、`cli.mjs` | 残留 / console / 同步 fs / 空 catch 等自动豁免 |
123
- | 私有库 / 技能文档 | 远端 `private`;`skills/`、`rules/` 下 md | private 时私密文件与拦截降级为只报告;文档里的沟通措辞不触发沟通词规则 |
124
-
125
- 标记清单:`dsh-skip-sensitive`(凭据/私密)、`dsh-skip-size`(大文件/二进制)、`dsh-skip-func-length`(函数超长)、`dsh-skip-complexity`(圈复杂度/嵌套)、`dsh-skip-syntax`(语法 / JSON / YAML 解析)、`dsh-skip-quality`(质量评分类)、`dsh-skip-residue`(debugger / todo / console)、`dsh-skip-style`(数值风格)、`dsh-skip-i18n`(硬编码文案)。
126
-
127
- ```js
128
- // dsh-skip-sensitive: 文件含 mock 凭据字面量(占位示例,非真实凭据)
129
- console.log(x); // dsh-skip-residue: 本行为刻意保留的调试输出样本
130
- ```
131
-
132
- `secret-*` / `cred*` / `security/*` 类规则即使标 `disabled` 也强制加载——安全红线不可豁免。
133
-
134
- ### 10. 链接检查(link_check)
135
-
136
- 工具 `link_check`(`path` = 文件或目录,默认工作区)、CLI `audit-sluice link-check <路径>`、斜杠命令 `/link-check [文件或目录]`。扫描 md / 文本内 URL 并访问验证:404 / 403 / 410 / 451 → 扣 3,DNS 失败 → 扣 2,超时 / 连接失败 / 5xx → 扣 1;只 warning,永不 blocker。配置 `linkCheckEnabled` 默认关(需要网络)。
137
-
138
- ### 11. 文档漂移检查(函数列表 / 目录树 / 版本表)
139
-
140
- `node scripts/doc-func.mjs check`(函数列表)、`node scripts/doc-tree.mjs check`(目录树)、`node scripts/doc-version.mjs check`(版本表)分别比对宿主 md 标记块与最新内容并报漂移。三个脚本都有 `gen`(只打印)/ `apply`(覆盖标记块)/ `check`(报漂移);函数列表由 AST 真实扫描生成,避免手工维护漂移。
141
-
142
- ### 12. 报告聚合与 YAML 输出
143
-
144
- - `groupBy` 四维度:`rule`(规则类型,默认)/ `file` / `severity` / `slot`(规则包);`groups` 按条数降序,每组带一条 `sample`;`severity` 白名单过滤 + `top` 截断(`0` = 全部),过滤后条数见 `filtered`。
145
- - `exemptStats` 输出本次被豁免的类型与数量;`blocked` 直接列出 blocker 明细(文件 / 行 / 规则 / 消息);YAML 报告:HTTP `withYaml=true` → `yaml` 字段,工具 `includeFindings=true` 时含 `yaml`。
146
-
147
- ### 13. 低成本整改:提取公共函数 = 一次动作多规则清零
148
-
149
- **先看计分口径(决定性价比)**
150
-
151
- | 口径 | 事实 | 含义 |
152
- |---|---|---|
153
- | 计数去重 | warning/info 按「规则 × 维度 × 文件」每文件每规则只计 1 次(blocker 每次计 2) | 同一文件同类问题修**一个代表点**,该文件对该规则的扣分即清零;warning 列表条数不受去重影响(想清空列表要逐条修或逐条豁免) |
154
- | scoreImpact | `0` 的 finding 不计分(魔数、嵌套深度、重复字面量、低风险 io-risk 等) | 冲分先修 `scoreImpact=1` 的规则;`0` 的只影响 warning 条数 |
155
- | 豁免等价 | 豁免标记会让 finding 直接消失、不计数 | 「修代码」与「加豁免」在**计分上等价**;区别只在代码质量本身与列表展示 |
156
- | 对数衰减 | 单维度 `max(0.1, 10 - k·ln(1+问题数))`(k:安全 1.5 / 可读·可维护·健壮 1.3 / 性能 1.1) | 计数从 20 降到 10 的收益远大于 10 降到 0;先处理计数高的维度 |
157
-
158
- **为什么提取公共函数最划算**
159
-
160
- 函数太长 / 嵌套太深 / 圈复杂度高 / 重复调用 / 重复代码,根因都是「没抽出公共函数」。抽一次,多条规则同时消失:
161
-
162
- | 规则 | 覆盖方式 |
163
- |---|---|
164
- | max-cyclomatic-complexity、max-nesting-depth、max-function-length | 直接:拆成子函数 + 早返回 |
165
- | repeat-identical-call | 直接:重复调用合并进一个 helper |
166
- | vague-function-name、variable-min-length、vague-variable-name | 顺带:提取时给函数/参数/局部变量起具名;契约要求导出名不变时用 `export { 具名实现 as run }`(模块仍只导出约定名) |
167
- | magic-number-smart、duplicate-constant-def、no-repeated-hardcoded-literals | 顺带:提取时把字面量提成命名常量 |
168
- | mkdir-before-write | 顺带:写操作移进公共函数后,写目标来自形参 ⇒ 规则语义豁免 |
169
- | comment/no-date、hardcoded-absolute-path、io-risk、memory-bomb | **不覆盖**:需单独处理(删日期 / 提候选常量+行级豁免 / 异步化或行级豁免 / 接受) |
170
-
171
- 实测(一次全量整改,29 文件):评分 83.0/B → 97.9/A,warning 99 → 5;其中「提取函数 + 顺带命名/常量化」覆盖约 55/99 条,其余 44 条是注释/路径/IO/内存类。
172
-
173
- **危险级不高的前提(照做才安全)**
174
-
175
- 1. 只搬运结构、不改行为:判断、异常、短路 return、错误处理边界保持原样。
176
- 2. 三类**不拆、改豁免**:
177
- - 跨回调共享闭包状态(如子进程 stdout/stderr/error/close/超时五路共享 settled 标志);
178
- - 字符级扫描器(字符串/注释/括号三态一次遍历,拆开反而割裂状态机);
179
- - 单调用点且拆完没有更清楚(过度抽象)。
180
- 3. 同步改异步会外溢:io-risk 真修成 async 会波及整条同步调用链(CLI/测试),多数场景行级 `dsh-skip-residue` 更划算。
181
- 4. 拆完必须复跑审计:新函数名/变量名可能触发新规则(实测:`handleXxxCommand` 被 io-risk 判成「请求处理路径」,把整文件同步 IO 从 low 升到 medium/high;局部变量取通用词名(如 result)会触发 vague-variable-name)。改名(如 `dispatchXxxCommand` / `actionResult`)后恢复。
182
- 5. 验证闭环:`node --test` + 重新全量审计,确认分数只升不降、无新 blocker。
183
-
184
- **操作顺序**:`groupBy=rule` 看明细 → 按「文件 × 规则」挑代表点 → 提取函数/常量/改名 → 复跑审计 → 只剩 `scoreImpact=1` 的顽固项时才逐条修或逐条豁免。
185
-
186
- ## 三、边界与坑
187
-
188
- | 现象 | 原因 | 处理 |
189
- |---|---|---|
190
- | 结果里出现 `audit/scan-truncated` | 文件数超 `maxScanFiles`(默认 3000,`0` = 不限) | 调大上限或设 0;截断会优先纳入变动文件,该条 `scoreImpact: 0` 不扣分 |
191
- | `quality` 为 null | 0 文件(空目录 / 0 变动) | 属正常「未评分」,不是满分 |
192
- | 分数与预期差很多 | 权重被 `weightOverrides` 覆盖 | 核对侧边栏权重 / `weights` / `--weights` 三处来源 |
193
- | 改了规则包不生效 | 改的是工作区文件,GUI 实际读安装版本 | 用 `scripts/rule-switch.mjs`(默认安装版本)或 `--workspace` 明确目标 |
194
- | 想靠豁免消掉误报 | 豁免是逃生门,不是修误报 | 判定类误报修 AST 精筛;豁免只用于刻意样本 |
195
- | 私有库被大量拦截 | 可见性探测失败按 `unknown` 保守拦截 | 确认 `origin` 指向;`private` 才只报告 |
196
- | `.auditignore` 不生效 | 写法不是 gitignore 语义 | 用 gitignore 语法;`*.sh` 匹配任意层级,只根目录用 `/*.sh` |
197
- | 自定规则目录参数名三端不同 | CLI 用 `--ruleset`,HTTP 用 `rulesetDir`,工具用法提示写作 `ruleset` | 以 CLI / HTTP 为准 |
198
-
199
- ## 四、配套 skill
200
-
201
- | skill | 用途 |
202
- |---|---|
203
- | skills/guide/guide-commit-push.md | 提交前审计门禁、拦截与放行字段、私有库豁免 |
204
- | skills/guide/guide-cli-scripts.md | 独立 CLI 与脚本(含 `git-sluice`、`rule-switch`) |
205
- | skills/guide/guide-slash-completion.md | 输入框斜杠命令(`/git-audit`、`/link-check`) |
206
- | skills/guide/guide-clone-repos.md | 克隆仓库与本地仓库扫描 |
207
-
208
- ## 14. 按插件架构修订规则,且按性价比取舍误报
209
-
210
- 规则不是通用前端 linter:它主要服务于 **DSH 插件**这种架构,判定要贴合插件真实形态,
211
- 否则「按通用项目写的判据」在插件上系统性失真。
212
-
213
- **已按插件架构落地的适配**
214
-
215
- | 插件架构事实 | 通用判据为何失真 | 规则怎么改 |
216
- |---|---|---|
217
- | 客户端是**构建产物**(`dsh.client` 指向单文件) | 产物行数天然超阈值 | `dsh-client-entry` 作用域降级为 info(仍报不扣分,不用 exempt 藏掉事实) |
218
- | 源码按**分片**维护(`lib/client-parts/**` → 拼接) | 分片是片段,单文件语法都不成立;创建元素与绑定事件可能在不同分片 | 标准 `client-parts/` 由 exclude_dirs 跳过且规模规则按 `dsh-client-fragment` 降级;自定义分片目录由 button-bind 降级 info(完整判定交给产物) |
219
- | 插件 UI 常用**事件委托** + 原生触发(label.click() 开文件框) | 只认 `addEventListener('click')` ⇒ 表单控件/文件框全被判未绑 | 按元素类型分流:button 要 click 类;input 接受 change/input/submit 等;`type=file` 有程序化触发即视为原生接好 |
220
- | 测试聚合文件(每条 `rec(...)` 一个用例) | 「文件长」被判臃肿,且只认 `function` ⇒ 箭头用例全部计 0 行 | 识别箭头/方法简写/asynс 体;最大函数≤阈值 → 聚合型 info;无函数时文案改成「顶层语句堆叠」而不是「藏着超大函数」 |
221
-
222
- **性价比取舍(不追求零误报)**
223
-
224
- 先算「修判定的成本 vs 这类误报的出现频率与危害」,再决定:
225
-
226
- - **值得修**:判定明确、可静态判定、且形态高频——如上面四类(事件类型、函数形态、产物/分片、聚合型文案)。
227
- 这类修一次,整类消失。
228
- - **不值得修(用豁免兜底)**:需要数据流/跨文件调用图才能证伪的判定——例如「事件委托是否真的覆盖某个
229
- `createElement` 出来的按钮」、跨文件(非分片)绑定、运行时动态注入。做精确分析的成本远超收益,
230
- 保留启发式判定 + `dsh-skip-quality` 文件头豁免。
231
- - **不算误报**:规则判对了事实、只是不想改(如自包含 151 行组件、静态自检页的装饰按钮)——
232
- 走豁免,不要改判定逻辑(否则会连带放过真问题)。
233
-
234
- **豁免的前提**:标记必须**真能生效**。历史上多次出现「规则 exemptHint 写着 `dsh-skip-quality`,
235
- 但该 kind 不在任何标记的 blocked 里」⇒ 用户按提示写了完全不生效(button-bind 就是 2026-10-24 补上的)。
236
- 新增 kind 时同步检查 `exemptHintForFinding({kind})` 是否返回标记。
237
-
238
- **判定引用范围时 grep 要 `-i`**:同一概念会以 `camelCase`/`PascalCase`/`SCREAMING_CASE`/`snake_case`
239
- 多种形态出现,小写搜会漏(实测:搜 `partFilter` 漏掉 `setPartFilter`,误判「零引用」而删掉底层实现)。
240
- 注意这只针对「人工核查引用」;规则内部的**标识符匹配必须保持大小写敏感**(JS/Python 本身区分大小写,
241
- 放宽只会引入新误报)。
242
-
243
- ## 15. 忽略链路(.gitignore / .auditignore)的测试纪律
244
-
245
- **这块历史上反复回归,而且每次都不是判定逻辑写错,而是接线层断掉。** 已知三次形态:
246
-
247
- | 回归形态 | 症状 | 为什么内部函数测试挡不住 |
248
- |---|---|---|
249
- | 以**空 stdin** 调 `check-ignore`,从未传文件路径 | 忽略集恒空 ⇒ 全仓文件都进审计 | `buildIgnoreSet` 内部逻辑没改,改的是它的输入 |
250
- | 大仓库降级:枚举全部文件被改成目录级判定 | 文件级规则(单个文件名)失效 | 降级是**性能分支**,内部单测仍走全量分支 |
251
- | 调用方**漏传 `gitIgnoreRoot`** | 函数默认值 `null` = 不判定忽略 ⇒ 忽略完全不生效 | 函数行为没变,变的是调用参数 |
252
-
253
- **纪律**:
254
-
255
- - 忽略相关改动必须跑**端到端**(`auditFull` / `runAudit`),不能只测 `collectTextFiles`。
256
- 既有 `test-collector-ignore.mjs` / `test-auditignore.mjs` 都只测内部函数,对上面三类天然失明;
257
- 端到端守门员是 `test/test-ignore-e2e.mjs`(三条链路 + 对照组)。
258
- - **必须有对照组**:断言「忽略的文件没出现」时,同时断言「该被审的文件出现了」。
259
- 否则「全部文件都被排除」也会让测试假通过。
260
- - 三条链路各自要有一条用例:full(走 `gitIgnoreRoot`)、diff(走 `collectChangedFiles` 独立路径)、
261
- 非 git 目录(git check-ignore 不可用,靠 `parseGitignore` 纯 JS 兜底)。
262
- - 样本要**入库**为固定 fixture(`test/fixtures/ignore-e2e/`),不要测试里现造:
263
- 现造样本会随实现漂移,也让「什么叫被忽略」没有唯一答案。
264
- 样本文件名用 `.js.fixture` / `.rules` 后缀——若直接叫 `gib.js` 且同目录放 `.gitignore`,
265
- 这两份样本自己就会被忽略而**无法入库**(自我反噬)。
266
- - 新增/修改忽略相关代码后,用「把 `gitIgnoreRoot` 强制改 `null`」自证测试会红——这是最容易复发的接线断点。
267
-
268
- **排查时的第一个坑(我踩过)**:直接调 `collectTextFiles(dir, { repoPath: dir })` 会得到
269
- 「忽略全失效」的假象——因为参数名是 `gitIgnoreRoot`,传错就等于显式关掉忽略判定。
270
- 复现前先确认自己的探针参数与真实调用方一致(见 `lib/audit/orchestrate.js` 的调用处)。
File without changes
File without changes