dsh-git-push 2.9.1 → 2.9.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.
package/README.md CHANGED
@@ -65,7 +65,7 @@ DSH(DeepSeek Harness)git 提交推送与代码审计插件——提交前自
65
65
  | 文档 | 讲什么 |
66
66
  |---|---|
67
67
  | [docs/SPEC.md](docs/SPEC.md) | **当前有效规格唯一入口**:身份 / 18 个工具 / 35 条 HTTP 接口 / 20 个设置键 / 4 个数据文件 / 审计规则体系 / 文档产物 / 版本纪律 / 测试基线 |
68
- | [docs/功能-审计规则体系.md](docs/功能-审计规则体系.md) | 22 个规则槽位 / 138 条规则的组织方式、作用域字段、三层结构、运行入口、结果怎么读、怎么豁免 |
68
+ | [docs/功能-审计规则体系.md](docs/功能-审计规则体系.md) | 22 个规则槽位 / 165 条规则的组织方式、作用域字段、三层结构、运行入口、结果怎么读、怎么豁免 |
69
69
  | [docs/功能-历史提交审计.md](docs/功能-历史提交审计.md) | 逐提交回放审计:解决什么、怎么跑、与普通审计的差异与成本 |
70
70
  | [docs/功能-文档与结构追踪.md](docs/功能-文档与结构追踪.md) | tree-doc / doc-func / doc-version 三份自动生成文档怎么更新、漂移怎么办 |
71
71
  | [docs/功能-仓库索引与账号状态.md](docs/功能-仓库索引与账号状态.md) | `dsh-repo-index.json` 与 `account-status.json` 的写入时机、读取入口、统一收口约定 |
@@ -88,7 +88,7 @@ DSH(DeepSeek Harness)git 提交推送与代码审计插件——提交前自
88
88
 
89
89
  | 功能块 | 做什么 | 入口 |
90
90
  |---|---|---|
91
- | **提交前审计门禁** | 提交前自动审计,blocker 拦截;22 个规则槽位 138 条规则、10 维度质量评分、豁免机制、链接检查、**三层审计管线(L1 正则初筛 / L2 AST 数据流 / L3 运行时检测)** | `code_audit` 工具 / CLI / 侧边栏 / 输入框 `/git-audit` |
91
+ | **提交前审计门禁** | 提交前自动审计,blocker 拦截;22 个规则槽位 165 条规则、10 维度质量评分、豁免机制、链接检查、**三层审计管线(L1 正则初筛 / L2 AST 数据流 / L3 运行时检测)** | `code_audit` 工具 / CLI / 侧边栏 / 输入框 `/git-audit` |
92
92
  | **审计结果 API** | `/api/git-push/audit`——请求时自定义聚合审计结果:按**规则类型 / 文件名 / 严重级 / 规则包**分组,`severity` 白名单过滤,`top` 截断,`withFindings` 附明细 | HTTP `GET/POST /api/git-push/audit` |
93
93
 
94
94
  ## 一、提交推送
@@ -282,6 +282,7 @@ dsh-git-push/
282
282
  │ │ ├── credential.js — 凭据标识符判定(硬编码/引用/类型检查)
283
283
  │ │ ├── dataflow.js — 数据流检查(清空后访问,三层审计 L2)
284
284
  │ │ ├── dup-code.js — (待注释)
285
+ │ │ ├── fs-hotspots.js — (待注释)
285
286
  │ │ ├── index.js — AST 层统一出口
286
287
  │ │ ├── io-risk-const.js — IO 风险分级·常量与档位工具:fs 调用名集/操作类别/风险标签/搜索窗口与阈值 + raise 升档
287
288
  │ │ ├── io-risk-fn.js — IO 风险分级·函数边界识别与 token 配对:认普通/箭头/方法简写/类方法,圆括号花括号方括号前后向配对
@@ -352,6 +353,7 @@ dsh-git-push/
352
353
  │ │ ├── file-health.js — 文件健康度(行数/字节/行长三维打分)
353
354
  │ │ ├── filter.js — 规则作用域过滤(exts/exclude_paths)
354
355
  │ │ ├── folder.js — 目录级检查(文件夹数/单目录文件数/解包特征)
356
+ │ │ ├── fs-scanner.js — (待注释)
355
357
  │ │ ├── hardcoded-path.js — (待注释)
356
358
  │ │ ├── index.js — 检查层统一出口
357
359
  │ │ ├── io.js — IO 风险分级包装:checkIoRisk → lib/ast/io-risk.js(转 warning finding,取代 quality/sync-fs)
@@ -493,6 +495,7 @@ dsh-git-push/
493
495
  │ ├── rule-switch.mjs — 规则槽位手动启停 CLI
494
496
  │ ├── rules-solo-audit.mjs — 规则单启控制变量扫描(基准全关+逐规则单启+全量对照,报告供 AI/人工审规则有效性与局限,按需运行非常驻)
495
497
  │ ├── scan-file-io.mjs — 文件读写扫描器(列出所有 fs 读写调用位置 + 路径参数)
498
+ │ ├── scan-fs-hotspots.mjs — (待注释)
496
499
  │ ├── scan-hardcoded-paths.mjs — (待注释)
497
500
  │ ├── scan-repos.mjs — (待注释)
498
501
  │ ├── scan-version.mjs — 版本一致性校验脚本
@@ -574,12 +577,14 @@ dsh-git-push/
574
577
  │ ├── test-empty-catch-promise.mjs — (待注释)
575
578
  │ ├── test-empty-catch-single-source.mjs — (待注释)
576
579
  │ ├── test-exempt-hint-classify.mjs — (待注释)
580
+ │ ├── test-exempt-hint-effective.mjs — (待注释)
577
581
  │ ├── test-exempt.mjs — 豁免总入口测试(7 标记 + 位置语义)
578
582
  │ ├── test-ext-variable-min-length.mjs — (待注释)
579
583
  │ ├── test-false-positive-fixes.mjs — 误报修复回归测试
580
584
  │ ├── test-file-health.mjs — 文件健康度矩阵评分测试
581
585
  │ ├── test-filter-ext.mjs — (待注释)
582
586
  │ ├── test-folder-scope.mjs — 目录级审计作用域回归测试
587
+ │ ├── test-fs-hotspots.mjs — (待注释)
583
588
  │ ├── test-func-doc-drift.mjs — (待注释)
584
589
  │ ├── test-generated-html-artifact.mjs — (待注释)
585
590
  │ ├── test-git-api-tool.mjs — (待注释)
@@ -33342,7 +33342,7 @@ window.__requireShim = function (name) {
33342
33342
  };
33343
33343
 
33344
33344
  // 宿主 settingsScope:真内存 store,set 后通知 → 界面真的跟着变
33345
- window.__SLOTS__ = {"comment":{"name":"注释质量检测规则(AI 交流注释识别)","description":"检测『用户指示 2』『用户原话』等 AI 协作残留注释","author":"DeepSeek","stats":{"blocker":6,"warning":1,"pass":0,"total":7,"source":"rules"},"disabled":false},"cpp":{"name":"C/C++ 审计规则集(占位)","description":"C/C++ 项目语言专用规则(占位——规则待补,槽位已就绪)","author":"DeepSeek","stats":{"blocker":0,"warning":0,"pass":0,"total":0,"source":"rules"},"disabled":false},"docs":{"name":"docs 审计规则(链接判断槽位)","description":"","author":"","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"dsh":{"name":"dsh 插件专属审计规则集","description":"针对 DeepSeek Harness 插件(cordis 形态)的结构、依赖、工具契约、patch 语义审计;单行正则可执行","author":"EIGHTfs","stats":{"blocker":6,"warning":3,"pass":0,"total":9,"source":"rules"},"disabled":false},"filehealth":{"name":"文件健康度矩阵评分规则集","description":"单文件健康度评估(行数40% + 大小35% + 行长25%),score<9 提示、<5 blocker","author":"DeepSeek","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"folder":{"name":"文件夹数量审计规则(防止解包/依赖/构建产物入库)","description":"","author":"","stats":{"blocker":1,"warning":3,"pass":0,"total":4,"source":"rules"},"disabled":false},"frontend":{"name":"前端 HTML 审计规则(内嵌管理界面)","description":"用于服务端内嵌管理界面,不面向搜索引擎","author":"DeepSeek","stats":{"blocker":6,"warning":13,"pass":7,"total":26,"source":"rules"},"disabled":false},"go":{"name":"Go 审计规则集(占位)","description":"Go 项目语言专用规则(占位——规则待补,槽位已就绪)","author":"DeepSeek","stats":{"blocker":0,"warning":0,"pass":0,"total":0,"source":"rules"},"disabled":false},"i18n":{"name":"国际化审计规则(i18n 六条转规则)","description":"","author":"","stats":{"blocker":0,"warning":3,"pass":0,"total":3,"source":"rules"},"disabled":true},"java":{"name":"Java/Kotlin 审计规则集","description":"Java/Kotlin 项目语言无关规则:命名规范、魔数、方法长度、嵌套深度、圈复杂度","author":"DeepSeek","stats":{"blocker":1,"warning":6,"pass":0,"total":7,"source":"rules"},"disabled":false},"nodejs":{"name":"Node.js 后端审计规则集","description":"覆盖命名规范、代码结构、安全性、健壮性、性能、测试、依赖等维度","author":"DeepSeek","stats":{"blocker":13,"warning":22,"pass":2,"total":37,"source":"rules"},"disabled":false},"npm":{"name":"npm 插件发布审计规则集","description":"针对要发布到 npm 的 dsh 插件:发布清单/依赖声明/凭据防泄漏/publishConfig 语义审计(只扫 package.json + .npmrc)","author":"EIGHTfs","stats":{"blocker":6,"warning":6,"pass":5,"total":17,"source":"rules"},"disabled":false},"paths":{"name":"路径类审计规则(硬编码绝对路径 / 路径穿越 / cd 兜底 / 写入忽略目录 / 旧凭据路径)","description":"","author":"","stats":{"blocker":1,"warning":4,"pass":0,"total":5,"source":"rules"},"disabled":false},"performance":{"name":"性能审计规则(memory-bomb 示范落地)","description":"","author":"","stats":{"blocker":2,"warning":9,"pass":0,"total":11,"source":"rules"},"disabled":false},"php":{"name":"PHP 审计规则集(占位)","description":"PHP 项目语言专用规则(占位——规则待补,槽位已就绪)","author":"DeepSeek","stats":{"blocker":0,"warning":0,"pass":0,"total":0,"source":"rules"},"disabled":false},"private":{"name":"私密文件拦截审计(强制槽位)","description":"","author":"EIGHTfs","stats":{"blocker":13,"warning":0,"pass":0,"total":13,"source":"rules"},"disabled":false},"python":{"name":"Python 审计规则集","description":"Python 项目语言无关规则:命名规范、魔数、函数长度、嵌套深度、圈复杂度、文件长度","author":"DeepSeek","stats":{"blocker":1,"warning":6,"pass":0,"total":7,"source":"rules"},"disabled":false},"robustness":{"name":"健壮性审计规则(写文件目录保障等)","description":"","author":"","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"rust":{"name":"Rust 审计规则集(占位)","description":"Rust 项目语言专用规则(占位——规则待补,槽位已就绪)","author":"DeepSeek","stats":{"blocker":0,"warning":0,"pass":0,"total":0,"source":"rules"},"disabled":false},"structure":{"name":"目录结构规范(本地定制版)","description":"dsh-git-push 目录结构取舍结论:lib/ 平铺即源码(不引入 src/)、docs/ skills/ 保留、无 script/config/dist/log 空目录;统一单数命名(tool/ test/ doc/,不用 tools/ tests/ docs/)","author":"EIGHTfs","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"swift":{"name":"Swift 审计规则集(占位)","description":"Swift 项目语言专用规则(占位——规则待补,槽位已就绪)","author":"DeepSeek","stats":{"blocker":0,"warning":0,"pass":0,"total":0,"source":"rules"},"disabled":false},"template":{"name":"自定义审计规则集","description":"根据项目需求自定义填充规则","author":"DeepSeek","stats":{"blocker":0,"warning":0,"pass":1,"total":1,"source":"rules"},"disabled":false}};
33345
+ window.__SLOTS__ = {"comment":{"name":"注释质量检测规则(AI 交流注释识别)","description":"检测『用户指示 2』『用户原话』等 AI 协作残留注释","author":"DeepSeek","stats":{"blocker":6,"warning":1,"pass":0,"total":7,"source":"rules"},"disabled":false},"cpp":{"name":"C/C++ 审计规则集(首版 · 语言专项)","description":"C/C++ 项目语言专用规则(pattern 层首版:using namespace/裸 new/不安全 C 串函数/malloc-free/catch-all)","author":"DeepSeek","stats":{"blocker":1,"warning":3,"pass":1,"total":5,"source":"rules"},"disabled":false},"docs":{"name":"docs 审计规则(链接判断槽位)","description":"","author":"","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"dsh":{"name":"dsh 插件专属审计规则集","description":"针对 DeepSeek Harness 插件(cordis 形态)的结构、依赖、工具契约、patch 语义审计;单行正则可执行","author":"EIGHTfs","stats":{"blocker":6,"warning":3,"pass":0,"total":9,"source":"rules"},"disabled":false},"filehealth":{"name":"文件健康度矩阵评分规则集","description":"单文件健康度评估(行数40% + 大小35% + 行长25%),score<9 提示、<5 blocker","author":"DeepSeek","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"folder":{"name":"文件夹数量审计规则(防止解包/依赖/构建产物入库)","description":"","author":"","stats":{"blocker":1,"warning":3,"pass":0,"total":4,"source":"rules"},"disabled":false},"frontend":{"name":"前端 HTML 审计规则(内嵌管理界面)","description":"用于服务端内嵌管理界面,不面向搜索引擎","author":"DeepSeek","stats":{"blocker":6,"warning":13,"pass":7,"total":26,"source":"rules"},"disabled":false},"go":{"name":"Go 审计规则集(首版 · 语言专项)","description":"Go 项目语言专用规则(pattern 层首版:panic/os.Exit/fmt.Print/context.TODO/unsafe)","author":"DeepSeek","stats":{"blocker":1,"warning":2,"pass":2,"total":5,"source":"rules"},"disabled":false},"i18n":{"name":"国际化审计规则(i18n 六条转规则)","description":"","author":"","stats":{"blocker":0,"warning":3,"pass":0,"total":3,"source":"rules"},"disabled":true},"java":{"name":"Java/Kotlin 审计规则集","description":"Java/Kotlin 项目语言无关规则:命名规范、魔数、方法长度、嵌套深度、圈复杂度","author":"DeepSeek","stats":{"blocker":1,"warning":6,"pass":0,"total":7,"source":"rules"},"disabled":false},"nodejs":{"name":"Node.js 后端审计规则集","description":"覆盖命名规范、代码结构、安全性、健壮性、性能、测试、依赖等维度","author":"DeepSeek","stats":{"blocker":13,"warning":22,"pass":2,"total":37,"source":"rules"},"disabled":false},"npm":{"name":"npm 插件发布审计规则集","description":"针对要发布到 npm 的 dsh 插件:发布清单/依赖声明/凭据防泄漏/publishConfig 语义审计(只扫 package.json + .npmrc)","author":"EIGHTfs","stats":{"blocker":6,"warning":6,"pass":5,"total":17,"source":"rules"},"disabled":false},"paths":{"name":"路径类审计规则(硬编码绝对路径 / 路径穿越 / cd 兜底 / 写入忽略目录 / 旧凭据路径)","description":"","author":"","stats":{"blocker":1,"warning":4,"pass":0,"total":5,"source":"rules"},"disabled":false},"performance":{"name":"性能审计规则(memory-bomb 示范落地)","description":"","author":"","stats":{"blocker":2,"warning":9,"pass":1,"total":12,"source":"rules"},"disabled":false},"php":{"name":"PHP 审计规则集(首版 · 语言专项)","description":"PHP 项目语言专用规则(pattern 层首版:eval/extract/调试输出/错误抑制/md5 口令/die-exit)","author":"DeepSeek","stats":{"blocker":2,"warning":2,"pass":2,"total":6,"source":"rules"},"disabled":false},"private":{"name":"私密文件拦截审计(强制槽位)","description":"","author":"EIGHTfs","stats":{"blocker":13,"warning":0,"pass":0,"total":13,"source":"rules"},"disabled":false},"python":{"name":"Python 审计规则集","description":"Python 项目语言无关规则:命名规范、魔数、函数长度、嵌套深度、圈复杂度、文件长度","author":"DeepSeek","stats":{"blocker":1,"warning":6,"pass":0,"total":7,"source":"rules"},"disabled":false},"robustness":{"name":"健壮性审计规则(写文件目录保障等)","description":"","author":"","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"rust":{"name":"Rust 审计规则集(首版 · 语言专项)","description":"Rust 项目语言专用规则(pattern 层首版:unwrap/unimplemented!/panic!/println!/unsafe)","author":"DeepSeek","stats":{"blocker":2,"warning":2,"pass":1,"total":5,"source":"rules"},"disabled":false},"structure":{"name":"目录结构规范(本地定制版)","description":"dsh-git-push 目录结构取舍结论:lib/ 平铺即源码(不引入 src/)、docs/ skills/ 保留、无 script/config/dist/log 空目录;统一单数命名(tool/ test/ doc/,不用 tools/ tests/ docs/)","author":"EIGHTfs","stats":{"blocker":0,"warning":1,"pass":0,"total":1,"source":"rules"},"disabled":false},"swift":{"name":"Swift 审计规则集(首版 · 语言专项)","description":"Swift 项目语言专用规则(pattern 层首版:try!/as!/fatalError/print 调试/隐式解包属性)","author":"DeepSeek","stats":{"blocker":1,"warning":3,"pass":1,"total":5,"source":"rules"},"disabled":false},"template":{"name":"自定义审计规则集","description":"根据项目需求自定义填充规则","author":"DeepSeek","stats":{"blocker":0,"warning":0,"pass":1,"total":1,"source":"rules"},"disabled":false}};
33346
33346
  window.__scopeSubs = [];
33347
33347
  window.__scopeMock = {
33348
33348
  getSnapshot: function () { return { status: 'ready', writable: true, value: window.__FAKE__ }; },
@@ -127,6 +127,7 @@ export const TOOL_REGISTRY = [
127
127
  { flag: 'old', type: 'string', desc: '要被替换的字面文本(含空白,必须精确匹配;别名 old_string)' },
128
128
  { flag: 'new', type: 'string', desc: "替换后的文本(别名 new_string);**必传**,要删除请显式传空串 ''" },
129
129
  { flag: 'all', type: 'boolean', desc: '替换全部匹配(默认 false:要求唯一匹配;别名 replace_all)' },
130
+ { flag: 'allowDuplicate', type: 'boolean', desc: '放行「替换后产物包含整份原文 / 原文出现多次」的写入(默认拒绝:该形态会把文档写重;确认无误再开)' },
130
131
  ],
131
132
  },
132
133
  {
@@ -291,13 +291,39 @@ async function callNpmPublishJob(args = {}, jobs, exec, log, env = {}, cfg = {})
291
291
  otp: args.otp || '',
292
292
  confirm: args.confirm === true,
293
293
  });
294
- const outcome = (r) => (r && r.ok
295
- // 完成态必须用宿主认可的枚举值:`completed`(不是 `done` ✗)——
296
- // 历史缺陷:这里写 `status:'done'`,宿主 job_output 的校验只认
297
- // running|stopping|completed|killed|failed ⇒ 已完成的 job 一律读不出(报
298
- // `"value.job.status" must be one of [...]`),表现为「等了很久,结果似乎没成功」✗。
299
- ? { status: 'completed', output: JSON.stringify(r) }
300
- : { status: 'failed', detail: String((r && (r.error || r.blocked)) || 'npm publish 失败'), output: JSON.stringify(r || {}) });
294
+ /**
295
+ * 把发包结果映射成宿主 job 的 {status, detail, output} —— **成功也必须给 detail**。
296
+ *
297
+ * 历史缺陷(2026-10-16 实测):成功分支只写了 `output`(JSON 字符串),没写 `detail`
298
+ * ⇒ 宿主 job 的完成回执里没有可读结果,`job_output` 读出来是「(no new output)」✗,
299
+ * 只能去翻插件日志与 registry 侧面确认(clone / commit+push 都有 detail ⇒ 只有 npm 空 ✗)。
300
+ *
301
+ * 完成态枚举值同理:宿主只认 completed(不是 done ✗,见下方历史注释)。
302
+ * detail 里附带**判读提示**,避免把「发布延迟」当失败、把「staged」当发布成功。
303
+ */
304
+ const outcome = (r) => {
305
+ const o = r || {};
306
+ if (o.ok) {
307
+ const what = [o.name, o.version].filter(Boolean).join('@') || '(未知包)';
308
+ const bits = [
309
+ o.dryRun ? '**未写入 registry**(dry-run)' : `已发布到 ${o.registry || cfg?.npmRegistry || 'registry.npmjs.org'}`,
310
+ what,
311
+ o.tag ? `tag ${o.tag}` : '',
312
+ Array.isArray(o.packList) ? `文件 ${o.packList.length}` : '',
313
+ o.packSize ? `packed ${(Number(o.packSize) / 1048576).toFixed(2)}MB` : '',
314
+ ].filter(Boolean).join(' · ');
315
+ const tail = o.dryRun
316
+ ? '真发需同时传 confirm=true 与 dryRun=false(不可撤销)'
317
+ : '⚠️ 刚发完在 registry 查不到多为**发布延迟**(等 3~5 分钟复测,不是失败);'
318
+ + '若 npm 账号开了 2FA 而未带 otp,发布会进 **staged**(需在 npm 网站批准或带 otp 重发)';
319
+ return { status: 'completed', detail: `${bits}。${tail}`, output: JSON.stringify(o) };
320
+ }
321
+ const err = String(o.error || o.blocked || 'npm publish 失败');
322
+ const hint = /EOTP|one-time pass/i.test(err) ? '(需要一次性口令:传 otp=<6 位码> 重发)'
323
+ : /E409|previously (published|staged)/i.test(err) ? '(该版本已存在或在 staged:改版本号,或先处理 staged 记录)'
324
+ : /E403/i.test(err) ? '(权限/2FA:检查 token 是否具备该包发布权限)' : '';
325
+ return { status: 'failed', detail: `${err}${hint}`, output: JSON.stringify(o) };
326
+ };
301
327
  if (!jobs || typeof jobs.start !== 'function') {
302
328
  const r = await doPublish();
303
329
  return { ok: true, async: false, result: r };
@@ -584,6 +610,8 @@ export async function callTool(toolName, args = {}, env = {}, cfg = defaultConfi
584
610
  old: args.old ?? args.old_string,
585
611
  new: args.new ?? args.new_string,
586
612
  all: (args.all ?? args.replace_all) === true,
613
+ // 逃生阀:默认拒绝「替换后产物包含整份原文 / 原文出现多次」(那种形态会把文档写重)
614
+ allowDuplicate: args.allowDuplicate === true,
587
615
  });
588
616
  return r.ok
589
617
  ? { ok: true, path: r.path, replaced: r.replaced, bytesBefore: r.bytesBefore, bytesAfter: r.bytesAfter }
@@ -0,0 +1,154 @@
1
+ /**
2
+ * AST 层 · FS 热点抽取(**单一实现**,供两处消费)
3
+ *
4
+ * ① 审计规则 `performance/multi-file-scanners`(仓库级:扫描实现 > 阈值 ⇒ notice)
5
+ * ② 独立 CLI `scripts/scan-fs-hotspots.mjs`(①stat 热点排序 + ④遍历入口 + ②③⑤ 明细)
6
+ *
7
+ * 【为什么要单独一个模块】同一份判据若在「审计规则」和「CLI」各写一套 ⇒ 必然漂移 ✗
8
+ * (本项目反复踩的坑)。这里只写一份,两边只做「取数 + 呈现」。
9
+ *
10
+ * 【口径来源】移植自 bench-template 的 scripts/scan-fs-hotspots.mjs(2026-10-16 交接),
11
+ * 但**函数边界用插件自己的 collectFuncRanges**(真括号配对)⇒ 比原脚本的正则更准 ✓
12
+ *
13
+ * ⚠️ 计数纪律:每个调用**只计一次**(先整文件扫一遍,再按字符位置归属到所属函数)。
14
+ * 反面教材(本文件第一版):先整文件收一遍、再每个函数各收一遍 ⇒ 同一调用被计两次 ✗
15
+ * ⇒ CLI 打出来 stat 48 而基线是 25 ✗(实测发现的真 bug)。
16
+ *
17
+ * 判据(六类,与交接文档一致):
18
+ * ① stat 调用点 —— 每个 stat 调用的 文件:行 + 所属函数 + 原始表达式(每条只出现一次)
19
+ * ② 重复 stat —— 同一函数内**同一表达式** stat ≥2 次(可合并成一次)
20
+ * ③ 重复 readdir —— 同一函数内同一表达式 readdir ≥2 次
21
+ * ④ 遍历入口 —— 函数体内有 readdir,且「自递归」或调用已知 walker 名
22
+ * ⑤ 逐文件扫描实现 —— 函数体内同时出现 readdir 与 stat ⇒ 一个「扫描器」实现
23
+ * ⑥ 汇总 —— 给调用方直接用的 totals
24
+ */
25
+ import { collectFuncRanges } from './perf.js';
26
+
27
+ /** 统计类调用(① 热点排序 / ⑤ 扫描器判定)。 */
28
+ const STAT_RE = /(?:^|[^\w$.])(?:fs\s*\.\s*)?(statSync|stat|lstatSync|lstat)\s*\(([^()]*)\)/g;
29
+ /** 目录列举类调用(③⑤④)。 */
30
+ const READDIR_RE = /(?:^|[^\w$.])(?:fs\s*\.\s*)?(readdirSync|readdir)\s*\(([^()]*)\)/g;
31
+ /** 已知遍历入口名(交接文档 §四.3 明说:这是名字白名单,新命名需补进来)。 */
32
+ export const FS_WALKERS = ['recursiveScanAll', 'walkWithIndex', 'scanDirShallow', 'recursiveScan', 'walkDir'];
33
+
34
+ /** 同函数内「同一表达式」的键:`statSync(dir)` —— 实参去空白。 */
35
+ const callKey = (name, args) => `${name}(${String(args).replace(/\s+/g, '')})`;
36
+
37
+ /** 字符偏移 → 行号(1-based)。 */
38
+ function lineAt(text, idx) {
39
+ let line = 1;
40
+ for (let i = 0; i < idx && i < text.length; i += 1) if (text[i] === '\n') line += 1;
41
+ return line;
42
+ }
43
+
44
+ /**
45
+ * 扫描单个文件的 FS 热点(每个调用只计一次)。
46
+ * @param {string} text 文件全文
47
+ * @param {string} [relPath] 相对路径(回填进结果,便于上层聚合与展示)
48
+ * @returns {{file:string, stats:Array, readdirs:Array, dupStats:Array, dupReaddirs:Array, walkers:Array, scanners:Array}}
49
+ */
50
+ export function scanFsHotspotsText(text = '', relPath = '') {
51
+ const s = String(text || '');
52
+ const out = {
53
+ file: relPath, stats: [], readdirs: [], dupStats: [], dupReaddirs: [], walkers: [], scanners: [],
54
+ };
55
+ const fns = collectFuncRanges(s);
56
+
57
+ /** 整文件扫一遍(**只此一次**):返回 {name,args,line,at,expr}。 */
58
+ const collect = (re) => {
59
+ const res = [];
60
+ re.lastIndex = 0;
61
+ let m;
62
+ while ((m = re.exec(s)) !== null) {
63
+ const at = m.index + (m[0].length - m[0].trimStart().length);
64
+ res.push({ name: m[1], args: m[2] || '', line: lineAt(s, at), at, expr: callKey(m[1], m[2] || '') });
65
+ }
66
+ return res;
67
+ };
68
+ /** 归属函数名(不在任何函数内 ⇒ '' = 顶层)。 */
69
+ const fnNameAt = (at) => {
70
+ const hit = fns.find((f) => at >= f.a && at <= f.b);
71
+ return hit ? hit.name : '';
72
+ };
73
+
74
+ for (const c of collect(STAT_RE)) out.stats.push({ ...c, fn: fnNameAt(c.at) });
75
+ for (const c of collect(READDIR_RE)) out.readdirs.push({ ...c, fn: fnNameAt(c.at) });
76
+
77
+ /** 同一组内「同一表达式出现 ≥2 次(且不同行)」⇒ 可合并。 */
78
+ const dups = (calls) => {
79
+ const seen = new Map();
80
+ const res = [];
81
+ for (const c of calls) {
82
+ if (seen.has(c.expr)) {
83
+ if (seen.get(c.expr) !== c.line) res.push(c);
84
+ } else seen.set(c.expr, c.line);
85
+ }
86
+ return res;
87
+ };
88
+
89
+ // 按「所属函数」分组(顶层同名归一组 ''),一次算出 ②③④⑤
90
+ const groups = new Map();
91
+ const groupOf = (fn, at) => {
92
+ const k = fn || '';
93
+ if (!groups.has(k)) groups.set(k, { fn: k, stats: [], readdirs: [], start: at });
94
+ return groups.get(k);
95
+ };
96
+ for (const c of out.stats) groupOf(c.fn, c.at).stats.push(c);
97
+ for (const c of out.readdirs) groupOf(c.fn, c.at).readdirs.push(c);
98
+
99
+ for (const g of groups.values()) {
100
+ out.dupStats.push(...dups(g.stats).map((c) => ({ ...c, fn: g.fn })));
101
+ out.dupReaddirs.push(...dups(g.readdirs).map((c) => ({ ...c, fn: g.fn })));
102
+ if (g.fn && g.readdirs.length && g.stats.length) {
103
+ out.scanners.push({ fn: g.fn, line: g.readdirs[0].line, readdir: g.readdirs[0].line, stat: g.stats[0].line });
104
+ }
105
+ // ④ 遍历入口:有 readdir,且(自递归 或 调用了已知 walker)
106
+ if (g.fn && g.readdirs.length) {
107
+ const r = fns.find((f) => f.name === g.fn);
108
+ if (r) {
109
+ const body = s.slice(r.a, r.b + 1);
110
+ const selfRe = new RegExp(`(?:^|[^\\w$.])${String(g.fn).replace(/\$/g, '\\$')}\\s*\\(`);
111
+ const walker = FS_WALKERS.find((w) => new RegExp(`(?:^|[^\\w$.])${w}\\s*\\(`).test(body));
112
+ if (selfRe.test(body) || walker) {
113
+ out.walkers.push({ fn: g.fn, line: lineAt(s, r.a), calls: walker || '(self)' });
114
+ }
115
+ }
116
+ }
117
+ }
118
+ return out;
119
+ }
120
+
121
+ /**
122
+ * 仓库级聚合:把每个文件的结果合并成「仓库视角」的汇总。
123
+ * @param {Array<{path:string, text:string}>} fileTexts
124
+ * @returns {{totals:object, files:Array, scanners:Array, dupStats:Array, dupReaddirs:Array, walkers:Array, hot:Array}}
125
+ */
126
+ export function scanFsHotspots(fileTexts = []) {
127
+ const files = [];
128
+ const scanners = [];
129
+ const dupStats = [];
130
+ const dupReaddirs = [];
131
+ const walkers = [];
132
+ const totals = { files: 0, stats: 0, readdirs: 0, dupStats: 0, dupReaddirs: 0, walkerCalls: 0, scanners: 0 };
133
+ for (const { path, text } of fileTexts) {
134
+ const r = scanFsHotspotsText(text, path);
135
+ files.push(r);
136
+ totals.files += 1;
137
+ totals.stats += r.stats.length;
138
+ totals.readdirs += r.readdirs.length;
139
+ totals.walkerCalls += r.walkers.length;
140
+ for (const x of r.scanners) scanners.push({ file: path, ...x });
141
+ for (const x of r.dupStats) dupStats.push({ file: path, ...x });
142
+ for (const x of r.dupReaddirs) dupReaddirs.push({ file: path, ...x });
143
+ for (const x of r.walkers) walkers.push({ file: path, ...x });
144
+ }
145
+ totals.scanners = scanners.length;
146
+ totals.dupStats = dupStats.length;
147
+ totals.dupReaddirs = dupReaddirs.length;
148
+ // ① stat 热点排序:按 stat 调用点数降序(CLI 用;审计规则不用)
149
+ const hot = files
150
+ .map((f) => ({ file: f.file, stats: f.stats.length, readdirs: f.readdirs.length }))
151
+ .filter((x) => x.stats > 0 || x.readdirs > 0)
152
+ .sort((a, b) => (b.stats - a.stats) || (b.readdirs - a.readdirs));
153
+ return { totals, files, scanners, dupStats, dupReaddirs, walkers, hot };
154
+ }
package/lib/ast/perf.js CHANGED
@@ -122,6 +122,15 @@ export function loopBodyLines(text = '') {
122
122
  * 实测不加这层收窄时,本仓库 184 个文件里误报 218 处(log/push/emit/readFile 等重复调用
123
123
  * 多是有意为之)。
124
124
  */
125
+ /**
126
+ * fs「属性/目录」查询类调用名(2026-10-16 判据②并入后新增的收窄白名单)。
127
+ * 为什么单列一份:这些调用每次都是一次真实系统调用 —— `statSync(p)` 在同一函数里写两遍
128
+ * 纯粹是浪费(可直接合并成一次 ✓),而 `resolve/findX` 那类只是"可能开销不小"。
129
+ * 只收**无副作用的查询型**(stat/lstat/readdir/exists/access/realpath,含 Sync 变体);
130
+ * 不收 readFile/write/unlink 等有副作用的 —— 重复调用可能是有意为之 ✗。
131
+ */
132
+ const FS_LIKE_RE = /(?:^|\.)?(?:stat|statSync|lstat|lstatSync|readdir|readdirSync|exists|existsSync|access|accessSync|realpath|realpathSync)$/;
133
+
125
134
  const LOOKUP_LIKE_RE = /(?:^|\.)?(?:resolve|lookup|canonical|toPath|find[A-Z]|get[A-Z]|parse[A-Z]|normalize[A-Z]|compute[A-Z]|build[A-Z]|read[A-Z])/;
126
135
 
127
136
  /**
@@ -141,23 +150,25 @@ function innermostLoopRanges(text) {
141
150
 
142
151
  /**
143
152
  * astConfirmKind: "repeat-identical-call" 的 **allow** 集合 ——
144
- * 同一个循环体内 ≥2 次**实参完全相同**的函数调用所在行。
153
+ * 同一**循环体**或同一**函数体**内 ≥2 次**实参完全相同**的函数调用所在行。
145
154
  *
146
155
  * 背景(真实案例):外部项目里 `resolveModuleToFilePath` 在解析循环中被调用 8762 次(约 180 次/文件),
147
156
  * 累计 4581ms 占全量扫描 89%;而 fs 探测只有 191 次/11ms —— 瓶颈是**重复纯计算**,
148
157
  * 加一层记忆化后该函数 4581ms → 344ms、整体 5143ms → 763ms。
149
158
  *
150
159
  * 判据与边界(宁可漏报不误报):
151
- * · 只看循环体内(复用 loopBodyLines);
160
+ * · 作用域 = 最内层循环体 ∪ 函数体(2026-10-16 扩:原只判循环内;FS 热点判据②并入本规则,
161
+ * 同一函数内同一表达式被 stat/readdir ≥2 次同样可合并成一次 ⇒ 由「函数体」这一档覆盖);
152
162
  * · 比较「函数名 + 实参文本(去空白)」完全相同 —— 实参不同的重复调用(如同名函数不同入参)
153
163
  * 不报,因为无法静态判断哪个更贵;
154
164
  * · 只匹配**无嵌套括号**的调用(保守,嵌套实参的调用一律不判);
155
165
  * · 排除注释/字符串里的示例。
156
166
  * 注意:本规则是**代理特征**——它抓「完全重复的调用」,而案例里更常见的是「入参部分重叠」,
157
167
  * 那类只能靠运行时探针(分阶段计时 + 调用计数)定位。
158
- * 收窄:只判**查询/解析类**函数名(resolve/lookup/findX/getX/parseX/normalizeX/computeX/buildX)——
159
- * 这类通常纯函数且可能开销不小;而 log/push/emit/readFile 之类重复调用多是有意为之
160
- * (实测不加这层收窄时,本仓库 184 个文件里误报 218 处)。
168
+ * 收窄:只判**查询/解析类**函数名(resolve/lookup/findX/getX/parseX/normalizeX/computeX/buildX)
169
+ * 与 **fs 属性类**(stat/lstat/readdir/exists/access/realpath 及其 Sync 变体)——
170
+ * 前者通常纯函数且可能开销不小,后者每次都是一次真实系统调用(重复即为纯浪费 ✓);
171
+ * 而 log/push/emit 之类重复调用多是有意为之(实测不加收窄时,本仓库 184 个文件里误报 218 处)。
161
172
  * @param {string} text 文件全文
162
173
  * @returns {Set<number>} 命中行号集合
163
174
  */
@@ -165,14 +176,14 @@ export function repeatIdenticalCallLines(text = '') {
165
176
  const s = String(text || '');
166
177
  const out = new Set();
167
178
  const tokens = tokenize(s);
168
- // 只比最内层循环区间:外层区间会把不同内层循环里文本相同的调用误判成重复(实测误报已修)
169
- for (const [a, b] of innermostLoopRanges(s)) {
179
+ /** 在 [a,b] 区间内收集「同键重复调用」的行号(键 = 函数名 + 去空白实参)。 */
180
+ const scanRange = (a, b) => {
170
181
  const body = s.slice(a, b + 1);
171
182
  const seen = new Map();
172
183
  const re = /([A-Za-z_$][\w.$]*)\s*\(([^()]*)\)/g;
173
184
  let m;
174
185
  while ((m = re.exec(body)) !== null) {
175
- if (!LOOKUP_LIKE_RE.test(m[1])) continue;
186
+ if (!LOOKUP_LIKE_RE.test(m[1]) && !FS_LIKE_RE.test(m[1])) continue;
176
187
  const line = lineOf(s, a + m.index);
177
188
  if (inCommentOrString(tokens, line, m[0])) continue;
178
189
  const key = `${m[1]}(${m[2].replace(/\s+/g, '')})`;
@@ -182,7 +193,12 @@ export function repeatIdenticalCallLines(text = '') {
182
193
  seen.set(key, line);
183
194
  }
184
195
  }
185
- }
196
+ };
197
+ // ① 最内层循环区间:外层区间会把不同内层循环里文本相同的调用误判成重复(实测误报已修)
198
+ for (const [a, b] of innermostLoopRanges(s)) scanRange(a, b);
199
+ // ② 函数体区间(判据②并入:同一函数内重复的 fs 属性调用同样可合并 ⇒ 一次系统调用省一次)
200
+ // 注意 collectFuncRanges 返回的是 [{name,a,b}](不是 [a,b] 对)
201
+ for (const { a, b } of collectFuncRanges(s)) scanRange(a, b);
186
202
  return out;
187
203
  }
188
204
 
@@ -223,7 +239,7 @@ export function loopFullCollectionLines(text = '') {
223
239
  // ============================================================
224
240
 
225
241
  /** 收集函数块体区间:function 声明 + 箭头函数块体。返回 [{name, a, b}](a/b 为块体内部区间)。 */
226
- function collectFuncRanges(text) {
242
+ export function collectFuncRanges(text) {
227
243
  const out = [];
228
244
  const re = /(?:async\s+)?function\s*([\w$]*)\s*\([^)]*\)\s*\{/g;
229
245
  let m;
@@ -20,6 +20,10 @@ const TEXT_EXT = new Set([
20
20
  'js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'json', 'yml', 'yaml', 'md', 'txt', 'html', 'css',
21
21
  'sh', 'py', 'rb', 'go', 'rs', 'java', 'c', 'cpp', 'h', 'hpp', 'xml', 'toml', 'ini', 'cfg',
22
22
  'conf', 'env', 'gitignore', 'npmrc', 'properties', 'sql', 'vue', 'svelte',
23
+ // 2026-10-16 补:PHP / Swift / Kotlin——此前只补了占位规则包 yml,**收集白名单没放行** ✗
24
+ // ⇒ 这两个语言的文件从来没进过审计管道,规则写了也永远 0 命中(实测合成样例 0 命中定位到此处)。
25
+ // phtml 是 PHP 模板扩展名(同 PHP 槽位 exts),kt 与 java 槽位共用一个包。
26
+ 'php', 'phtml', 'swift', 'kt',
23
27
  ]);
24
28
  /** git 探活 / 忽略清单批量判定 / 单目录判定 的超时(毫秒)。 */
25
29
  const GIT_PROBE_TIMEOUT_MS = 10_000;
@@ -1,8 +1,37 @@
1
+ import { exemptHintForFinding, exemptMarkerCovers } from '../exempt/index.js';
2
+
1
3
  /** 统一问题对象构造器(所有审计检查的出口)。 */
2
4
  export function makeFinding({ file, line, rule, kind, severity = 'warning', message, dimensions = [], exemptHint = '', scoreImpact = 0 }) {
3
5
  return { file, line, rule, kind, severity, message, dimensions, exemptHint, scoreImpact };
4
6
  }
5
7
 
8
+ /**
9
+ * 豁免提示「可信化」:把每个 finding 的 exemptHint 校正为**真能豁免它**的标记。
10
+ *
11
+ * 背景(2026-10-17 由「有人反应文件头豁免措辞无效」触发):exemptHint 是各检查器里**写死**的
12
+ * 字符串,而能否生效取决于 lib/exempt/index.js 的 blocked/细分清单。两者不一致时,用户照
13
+ * 提示写了文件头标记**仍然照报**(全量自证实测 24 种组合,如 readability/vague-function-name
14
+ * 提示 dsh-skip-residue、maintainability/max-cyclomatic-complexity 提示 dsh-skip-quality)。
15
+ * 做法:统一在这一处(所有 finding 的汇集点)用注册表反查校正——
16
+ * · 原提示的标记确实覆盖 ⇒ **保留**(不打扰已熟悉的措辞与既有豁免统计)
17
+ * · 不覆盖 ⇒ 换成真能豁免的标记 + 该标记的官方 hint
18
+ * · 一个都没有 ⇒ 如实说明「当前无可用标记」(不再给一个写了不生效的 ✗)
19
+ * 幂等:同一 finding 反复校正结果不变;对新规则同样生效(无需逐个检查器去改提示)。
20
+ * @param {Array} findings 统一问题对象数组(原地修正 exemptHint)
21
+ */
22
+ export function normalizeExemptHints(findings = []) {
23
+ const MARKER_RE = /dsh-skip-[a-z-]+/;
24
+ for (const f of findings) {
25
+ if (!f) continue;
26
+ const hit = String(f.exemptHint || '').match(MARKER_RE);
27
+ if (hit && exemptMarkerCovers(hit[0], f)) continue; // 原提示有效 ⇒ 保留
28
+ const truth = exemptHintForFinding(f);
29
+ if (truth) f.exemptHint = `${truth.marker}(${truth.hint})`;
30
+ else if (hit) f.exemptHint = '(当前无可用豁免标记:该 kind 不在任何 dsh-skip-* 的 blocked 清单里)';
31
+ }
32
+ return findings;
33
+ }
34
+
6
35
  /**
7
36
  * 扫描智能提示(1.0.8):对 warning/blocker 且文件路径或文件名带 test 特征的 finding,
8
37
  * 在 message 末尾附加「测试文件夹可用 .test 空文件豁免」提示(告知而非自动豁免——
@@ -24,7 +24,7 @@
24
24
 
25
25
  import '../rule/compilers.js'; // 副作用:注册 13 种编译函数
26
26
 
27
- export { makeFinding, decorateTestExemptHint, summarize, CODE_EXTS } from './finding.js';
27
+ export { makeFinding, decorateTestExemptHint, normalizeExemptHints, summarize, CODE_EXTS } from './finding.js';
28
28
  export { slotStatsFromFindings, buildRuleSlotMap, countRulesBySlot } from './slot.js';
29
29
  export { repoLevelSemanticRuleIds, pickRepoLevelAnchorFile } from './repo-level.js';
30
30
  export { hasMkdirInSameFunction, hasExternalCallTimeout, detectRepoJsYamlImport, isVersionInPathContext } from './file-context.js';
@@ -3,13 +3,13 @@ import { execFileSync } from 'node:child_process';
3
3
  import { join, relative } from 'node:path';
4
4
  import { collectTextFiles, readText, isGitRepo, collectChangedFiles, isTextFile } from './collector.js';
5
5
  import { computeAnalysisCoverage } from './analysis-coverage.js';
6
- import { groupByKind, HINT_QUALITY, checkFolderRules, checkPrivateFiles, checkDuplicateCode, checkDuplicateConst } from './checks.js';
6
+ import { groupByKind, HINT_QUALITY, checkFolderRules, checkPrivateFiles, checkDuplicateCode, checkDuplicateConst, checkMultiFileScanners } from './checks.js';
7
7
  import { loadRuleFiles } from '../rule/loader.js';
8
8
  import { compileAllRules } from '../rule/registry.js';
9
9
  import { auditFile } from './audit-file.js';
10
10
  import { grammarForExt, parseText, makeSyncConfirmer } from '../ast/treesitter.js';
11
11
  import { detectRepoJsYamlImport } from './file-context.js';
12
- import { decorateTestExemptHint, makeFinding, summarize } from './finding.js';
12
+ import { decorateTestExemptHint, makeFinding, summarize, normalizeExemptHints } from './finding.js';
13
13
  import { pickRepoLevelAnchorFile, repoLevelSemanticRuleIds } from './repo-level.js';
14
14
  import { checkDocsScore } from '../score/docs-score.js';
15
15
  import { runAuditExt } from './ext-runner.js';
@@ -229,6 +229,8 @@ async function auditFiles(repoPath, files, opts = {}) {
229
229
  // 放在逐文件循环后:需要全部文件文本才能跨文件聚合「同一结构 ≥3 处」。severity 恒 warning。
230
230
  if (grouped['duplicate-code']) {
231
231
  findings.push(...checkDuplicateCode(fileTexts, grouped['duplicate-code']));
232
+ // 逐文件扫描实现过多(仓库级,2026-10-16):同一函数里既 readdir 又 stat 的实现 > 阈值 ⇒ notice
233
+ findings.push(...checkMultiFileScanners(fileTexts, grouped['multi-file-scanners']));
232
234
  }
233
235
  // 跨文件同名常量重复定义检测(maintainability/duplicate-constant-def)——DRY 信号:
234
236
  // 同一阈值/长度/窗口常量散落多个模块(MAX_MSG_PREVIEW=80 三处实测),改一处漏多处——
@@ -283,6 +285,11 @@ async function auditFiles(repoPath, files, opts = {}) {
283
285
  try {
284
286
  findings.push(...(await runAuditExt(repoPath, { dir: opts.auditExtDir, log: opts.log })));
285
287
  } catch (e) { log?.warn?.(`审计扩展执行失败:${e?.message || e}`); }
288
+ // 豁免提示可信化(2026-10-17)—— **必须放在所有 finding 追加完之后**:
289
+ // 此前放在文件循环附近,后面还有 tree-doc/func-doc/split-docs/ignore/ext 五处追加 ⇒
290
+ // 那些 finding 绕过校正,自证里仍能看到「提示 dsh-skip-quality 却没有标记能豁免」✗。
291
+ // 统一校正为「真能豁免该 finding」的标记(提示与判定口径分离曾致 24 种组合写了不生效)。
292
+ normalizeExemptHints(findings);
286
293
  // 按规则包聚合命中数(侧边栏规则包列表的「拦截/警告/通过」= 实际命中数)
287
294
  const slotStats = slotStatsFromFindings(findings, buildRuleSlotMap(compiled), countRulesBySlot(compiled));
288
295
  // 文档加分制(0 分起、上限 10)——结构信号 + 交叉验证,**不进 findings**