dsh-git-push 2.9.9 → 2.10.1

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 (47) hide show
  1. package/README.md +22 -15
  2. package/lib/app/command-registry.js +1 -0
  3. package/lib/app/handlers/repos.js +18 -2
  4. package/lib/app/tool-call.js +6 -2
  5. package/lib/ast/brace.js +15 -0
  6. package/lib/ast/size.js +68 -1
  7. package/lib/audit/collector.js +13 -4
  8. package/lib/audit/ignore-blind.js +5 -4
  9. package/lib/audit/orchestrate.js +2 -1
  10. package/lib/audit-rules/audit-rules-frontend.yml +4 -4
  11. package/lib/checks/button-bind.js +61 -13
  12. package/lib/checks/dispatch.js +1 -1
  13. package/lib/checks/private.js +2 -1
  14. package/lib/checks/structural.js +10 -3
  15. package/lib/client-parts/{10-account.js → account.js} +1 -1
  16. package/lib/client-parts/{41-actions.js → actions.js} +3 -2
  17. package/lib/client-parts/{99-apply.js → apply.js} +2 -1
  18. package/lib/client-parts/{21-audit.js → audit.js} +5 -5
  19. package/lib/client-parts/{11-browser.js → browser.js} +15 -4
  20. package/lib/client-parts/{01-const.js → const.js} +11 -5
  21. package/lib/client-parts/{40-controller.js → controller.js} +4 -4
  22. package/lib/client-parts/{03-icons.js → icons.js} +1 -1
  23. package/lib/client-parts/{00-loader.js → loader.js} +1 -0
  24. package/lib/client-parts/{23-npm.js → npm.js} +3 -2
  25. package/lib/client-parts/{30-page.js → page.js} +1 -1
  26. package/lib/client-parts/{20-repo.js → repo.js} +2 -2
  27. package/lib/client-parts/{22-settings.js → settings.js} +1 -1
  28. package/lib/client-parts/{02-utils.js → utils.js} +1 -1
  29. package/lib/client.js +51 -30
  30. package/lib/context/index.js +2 -1
  31. package/lib/core/atomic-json.js +1 -1
  32. package/lib/exempt/index.js +7 -2
  33. package/lib/git/index-format.js +182 -0
  34. package/lib/git/index.js +1 -0
  35. package/lib/git/repo-index.js +41 -30
  36. package/lib/git/scan-runner.js +1 -1
  37. package/lib/npm/publish.js +14 -12
  38. package/lib/self/index.js +1 -1
  39. package/package.json +1 -1
  40. package/scripts/build-client.mjs +19 -14
  41. package/scripts/picker-repro.mjs +115 -0
  42. package/skills/dsh-repo-index.md +1 -1
  43. package/skills/guide/guide-audit.md +77 -3
  44. package/skills/guide/guide-cli-scripts.md +1 -1
  45. package/skills/guide/guide-clone-repos.md +2 -2
  46. package/skills/guide/guide-inject-ui.md +2 -2
  47. package/skills/workflow/README.md +1 -1
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: guide-audit
3
- description: dsh-git-push 代码审计:三个入口、审计范围、10 维度评分、规则包槽位、豁免机制、严重级与报告聚合。处理代码审计/质量评分类请求时加载。
4
- whenToUse: 要审计仓库、看质量分与问题明细、加停审计规则、豁免误报、查审计 API 时。
5
- updated: 2026-10-02
3
+ description: dsh-git-push 代码审计:三个入口、审计范围、10 维度评分、规则包槽位、豁免机制、严重级与报告聚合,以及低成本整改(提取公共函数一次动作多规则清零)。处理代码审计/质量评分/整改提分类请求时加载。
4
+ whenToUse: 要审计仓库、看质量分与问题明细、加停审计规则、豁免误报、查审计 API 时;要把审计分从 B 提到 A、低成本消 warning、规划重构整改时。
5
+ updated: 2026-10-18
6
6
  generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
7
7
  ---
8
8
 
@@ -144,6 +144,45 @@ console.log(x); // dsh-skip-residue: 本行为刻意保留的调试输出样本
144
144
  - `groupBy` 四维度:`rule`(规则类型,默认)/ `file` / `severity` / `slot`(规则包);`groups` 按条数降序,每组带一条 `sample`;`severity` 白名单过滤 + `top` 截断(`0` = 全部),过滤后条数见 `filtered`。
145
145
  - `exemptStats` 输出本次被豁免的类型与数量;`blocked` 直接列出 blocker 明细(文件 / 行 / 规则 / 消息);YAML 报告:HTTP `withYaml=true` → `yaml` 字段,工具 `includeFindings=true` 时含 `yaml`。
146
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
+
147
186
  ## 三、边界与坑
148
187
 
149
188
  | 现象 | 原因 | 处理 |
@@ -165,3 +204,38 @@ console.log(x); // dsh-skip-residue: 本行为刻意保留的调试输出样本
165
204
  | skills/guide/guide-cli-scripts.md | 独立 CLI 与脚本(含 `git-sluice`、`rule-switch`) |
166
205
  | skills/guide/guide-slash-completion.md | 输入框斜杠命令(`/git-audit`、`/link-check`) |
167
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
+ 放宽只会引入新误报)。
@@ -20,7 +20,7 @@ generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
20
20
  | `ruleset [槽位...]` | 编译规则包并输出统计 | 槽位名(可多个) |
21
21
  | `scan <root>` | 全量扫描目录(非 git 目录也能查) | `--depth N` |
22
22
  | `repos <root>` | 扫描本地 git 仓库(尊重 `.gitignore`,被忽略目录整棵跳过) | `--depth N`、`--max N`、`--json` |
23
- | `index <root>` | 重建仓库索引 `dsh-repo-index.json` | `--owner <账号>`、`--depth N`、`--max N`、`--offline`、`--json` |
23
+ | `index <root>` | 重建仓库索引 `dsh-repo-index.jsonl` | `--owner <账号>`、`--depth N`、`--max N`、`--offline`、`--json` |
24
24
  | `audit <root>` | 审计并输出质量评分与 findings | `--full`、`--level quick\|standard\|deep`、`--ruleset <目录>`、`--weights <JSON>`、`--include-ignored`、`--json` |
25
25
  | `commit <repo>` | 提交(可选推送) | `-m <msg>`、`--push`/`--no-push`、`--dry-run`、`--force`、`--req-confirm`、`--json` |
26
26
  | `link-check <路径>` | 检查 md/文本里的链接有效性(只 warning) | — |
@@ -22,7 +22,7 @@ generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
22
22
  | 本地仓库扫描 | `git_scan` 逐层下钻列仓库:分支 / 远端(脱敏)/ 未提交数 / 最近提交 / 领先落后 |
23
23
  | 远端仓库管理 | `git_remote_create` 建仓(默认 private,已存在则复用并设 origin);`git_set_visibility` 切 public/private |
24
24
  | 账号与配额 | 账号状态(离线读快照)/ 在线校验 / API 配额查询(`/rate_limit`,不消耗配额) |
25
- | 仓库索引 | 推送成功、云端加载、本地扫描时维护 `dsh-repo-index.json`;本地仓库列表据此标注每个仓库的 GitHub 归属 |
25
+ | 仓库索引 | 推送成功、云端加载、本地扫描时维护 `dsh-repo-index.jsonl`;本地仓库列表据此标注每个仓库的 GitHub 归属 |
26
26
 
27
27
  ## 二、怎么用(工具 + HTTP 接口参数表与返回字段)
28
28
 
@@ -169,5 +169,5 @@ git_set_visibility({ repo: "<本地仓库路径>", visibility: "private" })
169
169
  | `git_commit_push` | 克隆完成后的提交推送(审计门禁 + 凭据注入);推送成功会重建仓库索引 |
170
170
  | `git_sluice` | 在克隆下来的仓库里执行 log/diff/branch 等 git 命令(凭据自动注入) |
171
171
  | `git_account_check` / `git_cred_env` | 克隆私有库前先确认 token/SSH 可用;外部命令取凭据环境前缀 |
172
- | `dsh-repo-index.json` | 仓库索引(权威源码索引,存插件配置目录 `DSH_HOME/git-push/`):记录每个项目的仓库地址、可见性、恢复命令 `cloneCmd`、skills 与本地 `path`,`version` 恒为 1、`generatedAt` 每次刷新;源码丢失时按它 `git_clone` 恢复,本地列表据此标注仓库归属 |
172
+ | `dsh-repo-index.jsonl` | 仓库索引(权威源码索引,存插件配置目录 `DSH_HOME/git-push/`):记录每个项目的仓库地址、可见性、恢复命令 `cloneCmd`、skills 与本地 `path`,`version` 恒为 1、`generatedAt` 每次刷新;源码丢失时按它 `git_clone` 恢复,本地列表据此标注仓库归属 |
173
173
  | 侧边栏「账号信息 → 仓库管理」 | 本地子选项卡按索引标注归属并可 `push`;云端子选项卡「加载仓库列表」选目录后走同一套后台克隆 |
@@ -107,7 +107,7 @@ generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
107
107
 
108
108
  | 时机 | 账号信息 | 本地仓库列表 |
109
109
  |---|---|---|
110
- | 插件启动(侧边栏加载) | 离线读 `account-status.json` | 离线读 `dsh-repo-index.json` |
110
+ | 插件启动(侧边栏加载) | 离线读 `account-status.json` | 离线读 `dsh-repo-index.jsonl` |
111
111
  | 云端 push 完成后 | 离线读(push 时已在线更新 json) | 离线读(push 时已重建索引) |
112
112
  | 手动刷新 | `重新检测` = 在线校验写 json,再离线读回 | `扫描` = 独立进程后台离线扫描,逐条追加 |
113
113
 
@@ -137,7 +137,7 @@ generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
137
137
  |---|---|
138
138
  | `config.json` | 全部设置与凭据真源(0600):开关、扫描范围、文件上限、权重覆盖、规则包顺序、推送通道/门禁、自动推送、`githubToken`、`sshPub`,以及可选的 `injectUsageText` |
139
139
  | `account-status.json` | 账号快照:登录名、是否登录、token/SSH 各自有效性与校验时间 |
140
- | `dsh-repo-index.json` | 仓库索引:本地/云端仓库的归属、可见性、路径、默认分支、领先/落后等(自动生成,请勿手改) |
140
+ | `dsh-repo-index.jsonl` | 仓库索引:本地/云端仓库的归属、可见性、路径、默认分支、领先/落后等(自动生成,请勿手改) |
141
141
  | `scan-live.json` | 本地扫描进度:`version` / 已发现仓库 / 是否完成 |
142
142
  | `tools.json` | 工具探测结果(工具名 → 本机实测路径) |
143
143
  | `settings-ui.log` | 侧边栏每次保存设置的追加日志(凭据值打码) |
@@ -18,4 +18,4 @@ generatedBy: deepseek-official/deepseek-v4-flash · EIGHTfs 2026-10-02
18
18
  ## 已内置化
19
19
 
20
20
  - 开发者要求清单 → `lib/user-requirements.json`(随插件分发;v2 未移植,待验收)
21
- - 仓库索引 → 废弃 md 表格,改用 JSON 索引(生成于插件配置目录的 `dsh-repo-index.json`)
21
+ - 仓库索引 → 废弃 md 表格,改用 JSON 索引(生成于插件配置目录的 `dsh-repo-index.jsonl`)