dsh-git-push 2.20.18 → 3.0.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 (198) hide show
  1. package/README.md +3 -2
  2. package/cli-tool.mjs +2 -4
  3. package/cli.mjs +36 -2
  4. package/lib/app/apply.js +9 -9
  5. package/lib/app/command-registry.js +44 -20
  6. package/lib/app/handlers/meta.js +7 -142
  7. package/lib/app/handlers/npm.js +18 -1
  8. package/lib/app/handlers/preprocess.js +107 -0
  9. package/lib/app/handlers/repo-actions.js +2 -2
  10. package/lib/app/http-handlers.js +25 -12
  11. package/lib/app/index.js +2 -1
  12. package/lib/app/inject-text.js +3 -2
  13. package/lib/app/preprocess-client.js +136 -0
  14. package/lib/app/repo-ownership.js +1 -1
  15. package/lib/app/schema.js +3 -3
  16. package/lib/app/severity.js +14 -0
  17. package/lib/app/slash-commands.js +5 -164
  18. package/lib/app/tool-call.js +75 -140
  19. package/lib/app/tools.js +13 -6
  20. package/lib/cli/commands-preprocess.mjs +74 -0
  21. package/lib/cli/commands-tool.mjs +3 -2
  22. package/lib/cli/commands-vcs.mjs +4 -4
  23. package/lib/cli/shared.mjs +42 -13
  24. package/lib/client-parts/git/controller.js +2 -2
  25. package/lib/client.js +2 -2
  26. package/lib/commit-push/pre-commit-engine.js +57 -10
  27. package/lib/commit-push.js +125 -36
  28. package/lib/{exempt/index.js → git/exempt-markers.js} +8 -1
  29. package/lib/git/ignore.js +1 -1
  30. package/lib/git/repos.js +2 -2
  31. package/lib/git/sensitive.js +1 -1
  32. package/lib/npm/publish.js +20 -5
  33. package/lib/plugin/auto-push.js +2 -2
  34. package/lib/preprocess/providers.js +191 -0
  35. package/lib/self/index.js +1 -1
  36. package/lib/skip-dirs.js +14 -55
  37. package/package.json +29 -37
  38. package/scripts/build-client.mjs +2 -0
  39. package/scripts/check.mjs +4 -2
  40. package/scripts/local-registry.mjs +2 -1
  41. package/skills/dev/dsh-git-push.md +5 -0
  42. package/cli-audit.mjs +0 -141
  43. package/lib/app/audit-api.js +0 -173
  44. package/lib/app/host-doc-checks.js +0 -25
  45. package/lib/app/scope-check.js +0 -69
  46. package/lib/ast/brace.js +0 -120
  47. package/lib/ast/callgraph.js +0 -135
  48. package/lib/ast/code-lines.js +0 -175
  49. package/lib/ast/consts.js +0 -12
  50. package/lib/ast/control-flow.js +0 -470
  51. package/lib/ast/credential.js +0 -315
  52. package/lib/ast/dataflow.js +0 -391
  53. package/lib/ast/dup-code.js +0 -165
  54. package/lib/ast/fs-hotspots.js +0 -154
  55. package/lib/ast/index.js +0 -38
  56. package/lib/ast/io-risk-const.js +0 -95
  57. package/lib/ast/io-risk-fn.js +0 -208
  58. package/lib/ast/io-risk-loop.js +0 -308
  59. package/lib/ast/io-risk.js +0 -314
  60. package/lib/ast/lang.js +0 -156
  61. package/lib/ast/line-count.js +0 -52
  62. package/lib/ast/magic-number.js +0 -272
  63. package/lib/ast/naming.js +0 -292
  64. package/lib/ast/perf.js +0 -488
  65. package/lib/ast/scope-collisions.js +0 -228
  66. package/lib/ast/scope.js +0 -241
  67. package/lib/ast/shell.js +0 -131
  68. package/lib/ast/size.js +0 -448
  69. package/lib/ast/symbol-index.js +0 -399
  70. package/lib/ast/tokenizer.js +0 -421
  71. package/lib/ast/treesitter.js +0 -413
  72. package/lib/audit/analysis-coverage.js +0 -98
  73. package/lib/audit/audit-file.js +0 -205
  74. package/lib/audit/auditignore-rules.js +0 -148
  75. package/lib/audit/checks.js +0 -17
  76. package/lib/audit/client-entry.js +0 -93
  77. package/lib/audit/collector.js +0 -610
  78. package/lib/audit/ext-runner.js +0 -80
  79. package/lib/audit/file-context.js +0 -391
  80. package/lib/audit/finding.js +0 -101
  81. package/lib/audit/gitignore-match.js +0 -113
  82. package/lib/audit/glob.js +0 -63
  83. package/lib/audit/history-report.js +0 -100
  84. package/lib/audit/history.js +0 -126
  85. package/lib/audit/ignore-blind.js +0 -102
  86. package/lib/audit/index.js +0 -33
  87. package/lib/audit/orchestrate.js +0 -672
  88. package/lib/audit/public.js +0 -24
  89. package/lib/audit/repo-level.js +0 -30
  90. package/lib/audit/report-yaml.js +0 -90
  91. package/lib/audit/scope-policy.js +0 -110
  92. package/lib/audit/slot.js +0 -66
  93. package/lib/audit-rules/audit-rules-comment.yml +0 -199
  94. package/lib/audit-rules/audit-rules-cpp.yml +0 -114
  95. package/lib/audit-rules/audit-rules-csharp.yml +0 -82
  96. package/lib/audit-rules/audit-rules-docs.yml +0 -32
  97. package/lib/audit-rules/audit-rules-dsh.yml +0 -177
  98. package/lib/audit-rules/audit-rules-filehealth.yml +0 -42
  99. package/lib/audit-rules/audit-rules-folder.yml +0 -99
  100. package/lib/audit-rules/audit-rules-frontend.yml +0 -335
  101. package/lib/audit-rules/audit-rules-go.yml +0 -103
  102. package/lib/audit-rules/audit-rules-i18n.yml +0 -45
  103. package/lib/audit-rules/audit-rules-java.yml +0 -105
  104. package/lib/audit-rules/audit-rules-nodejs.yml +0 -662
  105. package/lib/audit-rules/audit-rules-npm.yml +0 -187
  106. package/lib/audit-rules/audit-rules-paths.yml +0 -98
  107. package/lib/audit-rules/audit-rules-performance.yml +0 -245
  108. package/lib/audit-rules/audit-rules-php.yml +0 -101
  109. package/lib/audit-rules/audit-rules-private.yml +0 -24
  110. package/lib/audit-rules/audit-rules-python.yml +0 -106
  111. package/lib/audit-rules/audit-rules-robustness.yml +0 -31
  112. package/lib/audit-rules/audit-rules-rust.yml +0 -109
  113. package/lib/audit-rules/audit-rules-structure.yml +0 -158
  114. package/lib/audit-rules/audit-rules-swift.yml +0 -99
  115. package/lib/audit-rules/audit-rules-template.yml +0 -108
  116. package/lib/audit-ui-sdk/contract.js +0 -117
  117. package/lib/audit-ui-sdk/index.js +0 -17
  118. package/lib/checks/button-bind.js +0 -347
  119. package/lib/checks/common.js +0 -170
  120. package/lib/checks/credential-file.js +0 -43
  121. package/lib/checks/dataflow.js +0 -40
  122. package/lib/checks/dispatch.js +0 -117
  123. package/lib/checks/dup-code.js +0 -69
  124. package/lib/checks/dup-const.js +0 -232
  125. package/lib/checks/file-health.js +0 -150
  126. package/lib/checks/filter.js +0 -137
  127. package/lib/checks/folder.js +0 -173
  128. package/lib/checks/fs-scanner.js +0 -57
  129. package/lib/checks/hardcoded-path.js +0 -98
  130. package/lib/checks/index.js +0 -49
  131. package/lib/checks/io.js +0 -66
  132. package/lib/checks/magic-number.js +0 -42
  133. package/lib/checks/npm-json.js +0 -273
  134. package/lib/checks/private.js +0 -64
  135. package/lib/checks/regex.js +0 -298
  136. package/lib/checks/scope-collision.js +0 -68
  137. package/lib/checks/semantic.js +0 -134
  138. package/lib/checks/structural.js +0 -281
  139. package/lib/cli/commands-audit.mjs +0 -142
  140. package/lib/cli/commands-doc.mjs +0 -127
  141. package/lib/client-parts/audit/audit.js +0 -301
  142. package/lib/exempt/tool.js +0 -198
  143. package/lib/git/module-splitter.js +0 -47
  144. package/lib/link-check/index.js +0 -187
  145. package/lib/lint-adapter/detect.js +0 -161
  146. package/lib/lint-adapter/index.js +0 -50
  147. package/lib/lint-adapter/runner.js +0 -133
  148. package/lib/rule/compilers/credential.js +0 -62
  149. package/lib/rule/compilers/dataflow.js +0 -38
  150. package/lib/rule/compilers/file-health.js +0 -75
  151. package/lib/rule/compilers/frontend.js +0 -86
  152. package/lib/rule/compilers/func.js +0 -35
  153. package/lib/rule/compilers/helpers.js +0 -71
  154. package/lib/rule/compilers/index.js +0 -29
  155. package/lib/rule/compilers/link-semantic.js +0 -45
  156. package/lib/rule/compilers/list-kinds.js +0 -12
  157. package/lib/rule/compilers/numeric-kinds.js +0 -73
  158. package/lib/rule/compilers/regex.js +0 -78
  159. package/lib/rule/compilers/structure.js +0 -107
  160. package/lib/rule/compilers.js +0 -17
  161. package/lib/rule/homoglyph.js +0 -45
  162. package/lib/rule/loader.js +0 -274
  163. package/lib/rule/registry.js +0 -122
  164. package/lib/rule/scope.js +0 -67
  165. package/lib/score/docs-score.js +0 -166
  166. package/lib/score/index.js +0 -234
  167. package/scripts/__pycache__/module-splitter.cpython-38.pyc +0 -0
  168. package/scripts/audit-ext/_example-readme-present.mjs +0 -34
  169. package/scripts/audit-ext/dsh-inject-declarations.mjs +0 -209
  170. package/scripts/audit-ext/variable-min-length.mjs +0 -102
  171. package/scripts/audit-gate.mjs +0 -235
  172. package/scripts/audit-runner.mjs +0 -35
  173. package/scripts/audit-runtime-check.mjs +0 -129
  174. package/scripts/browser-page-probe.mjs +0 -271
  175. package/scripts/check-js-scope.mjs +0 -87
  176. package/scripts/clean-date-comments.py +0 -102
  177. package/scripts/cpu-sample.mjs +0 -188
  178. package/scripts/doc-drift.mjs +0 -200
  179. package/scripts/hot-path-probe-cjs.cjs +0 -71
  180. package/scripts/hot-path-probe-fs-shim.mjs +0 -28
  181. package/scripts/hot-path-probe-fsp-shim.mjs +0 -31
  182. package/scripts/hot-path-probe.mjs +0 -153
  183. package/scripts/module-splitter.py +0 -800
  184. package/scripts/picker-repro.mjs +0 -115
  185. package/scripts/platform-scan.mjs +0 -168
  186. package/scripts/probe-recheck.mjs +0 -47
  187. package/scripts/rename-locator.mjs +0 -97
  188. package/scripts/rule-switch.mjs +0 -97
  189. package/scripts/rules-solo-audit.mjs +0 -173
  190. package/scripts/scan-file-io.mjs +0 -717
  191. package/scripts/scan-fs-hotspots.mjs +0 -107
  192. package/scripts/symbol-index.mjs +0 -85
  193. package/scripts/verify-prestep.mjs +0 -100
  194. package/skills/dev/audit-rule-authoring.md +0 -58
  195. package/skills/guide/guide-audit.md +0 -270
  196. /package/lib/{audit → app}/ownership.js +0 -0
  197. /package/lib/app/{schema-audit.js → schema-preprocess.js} +0 -0
  198. /package/lib/{audit-defaults.js → git/defaults.js} +0 -0
@@ -1,107 +0,0 @@
1
- #!/usr/bin/env node
2
- /**
3
- * dsh-git-push — FS 热点静态扫描(独立 CLI,咨询性,恒退出码 0)
4
- *
5
- * 用法:
6
- * node scripts/scan-fs-hotspots.mjs [root] [--json] [--top N] [--include 子串] [--exclude 子串] [--include-tests]
7
- *
8
- * 判据(六类,与审计规则 performance/multi-file-scanners 同源 ✓):
9
- * ① stat 热点 按 stat 调用点数排序的文件
10
- * ② 重复 stat 同一函数内同一表达式 stat ≥2 次
11
- * ③ 重复 readdir 同一函数内同一表达式 readdir ≥2 次
12
- * ④ 遍历入口 readdir + (自递归 或 已知 walker 名)
13
- * ⑤ 逐文件扫描实现 同一函数内既有 readdir 又有 stat
14
- * ⑥ 汇总 totals
15
- *
16
- * 【为什么不自己再写一遍判据】判据实现只在 lib/ast/fs-hotspots.js 一份 —— 审计规则
17
- * (lib/checks/fs-scanner.js)与 CLI 都用它 ⇒ 不会出现「脚本说 9 个、规则说 7 个」的漂移 ✗
18
- * (2026-10-16 由 bench-template 的 scan-fs-hotspots.mjs 交接而来:规则化 + 复用插件 tokenizer)
19
- * 【退出码恒 0】这是**咨询性报告**,不拦提交(要拦走审计规则 ✓)
20
- * dsh-skip-i18n: 用户可见文案硬编码为产品设计
21
- */
22
- import { readFileSync, readdirSync } from 'node:fs';
23
- import { join, relative, extname } from 'node:path';
24
- import { scanFsHotspots, FS_WALKERS } from '../lib/ast/fs-hotspots.js';
25
-
26
- /** 默认豁免目录(与审计规则口径一致:审计侧由 collector 跳过,这里显式列同一份)。 */
27
- const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'release', '.trash', '.auto-update-tmp', 'cache-index', 'cache-gifs', '__pycache__']);
28
- const TEST_DIRS = new Set(['test', 'tests']);
29
- const EXTS = new Set(['.js', '.mjs', '.cjs']);
30
-
31
- function parseArgs(argv) {
32
- const o = { root: process.cwd(), json: false, top: 10, include: '', exclude: '', includeTests: false };
33
- for (let i = 0; i < argv.length; i += 1) {
34
- const a = argv[i];
35
- if (a === '--json') o.json = true;
36
- else if (a === '--top') o.top = Number(argv[++i]) || 10;
37
- else if (a === '--include') o.include = String(argv[++i] || '');
38
- else if (a === '--exclude') o.exclude = String(argv[++i] || '');
39
- else if (a === '--include-tests') o.includeTests = true;
40
- else if (!a.startsWith('--')) o.root = a;
41
- }
42
- return o;
43
- }
44
-
45
- /** 递归收集待扫文件(跳过 SKIP_DIRS;test/tests 默认跳过,--include-tests 纳入 ✓)。 */
46
- function collectFiles(dir, o, out = []) {
47
- let ents = [];
48
- try {
49
- ents = readdirSync(dir, { withFileTypes: true });
50
- } catch {
51
- return out; // 权限/竞态:跳过该目录,不让整轮失败
52
- }
53
- for (const e of ents) {
54
- const full = join(dir, e.name);
55
- if (e.isDirectory()) {
56
- if (SKIP_DIRS.has(e.name)) continue;
57
- if (!o.includeTests && TEST_DIRS.has(e.name)) continue;
58
- collectFiles(full, o, out);
59
- } else if (EXTS.has(extname(e.name))) {
60
- const rel = relative(o.root, full);
61
- if (o.include && !rel.includes(o.include)) continue;
62
- if (o.exclude && rel.includes(o.exclude)) continue;
63
- out.push(full);
64
- }
65
- }
66
- return out;
67
- }
68
-
69
- const opts = parseArgs(process.argv.slice(2));
70
- const files = collectFiles(opts.root, opts);
71
- const fileTexts = files.map((full) => {
72
- try {
73
- return { path: relative(opts.root, full), text: readFileSync(full, 'utf8') };
74
- } catch {
75
- return { path: relative(opts.root, full), text: '' };
76
- }
77
- });
78
- const agg = scanFsHotspots(fileTexts);
79
-
80
- if (opts.json) {
81
- console.log(JSON.stringify({
82
- root: opts.root,
83
- includeTests: opts.includeTests,
84
- walkerNames: FS_WALKERS,
85
- totals: agg.totals,
86
- hot: agg.hot.slice(0, opts.top),
87
- scanners: agg.scanners,
88
- dupStats: agg.dupStats,
89
- dupReaddirs: agg.dupReaddirs,
90
- walkers: agg.walkers,
91
- }, null, 2));
92
- } else {
93
- const t = agg.totals;
94
- console.log(`FS 热点扫描(${t.files} 文件 · stat ${t.stats} · readdir ${t.readdirs} · 重复 stat ${t.dupStats} · 重复 readdir ${t.dupReaddirs} · 遍历入口 ${t.walkerCalls} · 逐文件扫描实现 ${t.scanners})`);
95
- console.log('\n① stat 热点(按 stat 调用点数):');
96
- for (const h of agg.hot.slice(0, opts.top)) console.log(` ${String(h.stats).padStart(3)} stat / ${String(h.readdirs).padStart(3)} readdir ${h.file}`);
97
- console.log('\n④ 遍历入口(readdir + 自递归/已知 walker):');
98
- if (!agg.walkers.length) console.log(' (无)');
99
- for (const w of agg.walkers) console.log(` ${w.file}:${w.line} ${w.fn}() → ${w.calls}`);
100
- if (agg.dupStats.length || agg.dupReaddirs.length) {
101
- console.log('\n②③ 同函数内重复的 stat/readdir(可合并成一次):');
102
- for (const d of [...agg.dupStats, ...agg.dupReaddirs]) console.log(` ${d.file}:${d.line} ${d.fn}() ${d.expr}`);
103
- }
104
- console.log(`\n⑤ 逐文件扫描实现(readdir+stat 同函数,共 ${agg.scanners.length} 个;> 3 时审计规则 performance/multi-file-scanners 会报 notice):`);
105
- for (const s of agg.scanners) console.log(` ${s.file}:${s.line} ${s.fn}()`);
106
- }
107
- process.exit(0); // 咨询性:恒 0(要拦提交走审计规则 ✓)
@@ -1,85 +0,0 @@
1
- /**
2
- * 跨文件符号索引 CLI —— 把 lib/ast/symbol-index.js 的能力做成可直接跑的命令。
3
- *
4
- * 用途:不用起插件/服务,直接对一个仓库出「符号索引 + 跨文件调用边 + 未使用导出候选 + 覆盖率」。
5
- * 覆盖率 = 连边数 / 可解析调用数(成员调用 `x.y()` 已排除并单独计数),是判断静态分析
6
- * 「到底解析到了多少」的置信度指标——只看命中数会被「其实没解析到」误导。
7
- *
8
- * 用法(在插件仓库根目录执行):
9
- * node scripts/symbol-index.mjs <仓库目录> [--json] [--unused] [--top N] [--ext .js,.mjs]
10
- * 例:
11
- * node scripts/symbol-index.mjs ../dsh-git-push --unused
12
- * node scripts/symbol-index.mjs ../dsh-codegraph --ext .ts --json > /tmp/idx.json
13
- */
14
- import { readFileSync, readdirSync, statSync } from 'node:fs';
15
- import { join, relative, resolve } from 'node:path';
16
-
17
- import { buildSymbolIndex, indexSummary, unusedExportCandidates } from '../lib/ast/symbol-index.js';
18
-
19
- const SKIP_DIRS = new Set(['.git', 'node_modules', '.trash', '.codegraph', 'dist', 'build', '__pycache__', '.archify']);
20
- const DEFAULT_EXTS = ['.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx'];
21
-
22
- /** 递归收集源码文件(相对路径,正斜杠)。 */
23
- function collectFiles(root, exts, dir = root, out = []) {
24
- let entries = [];
25
- try { entries = readdirSync(dir); } catch { return out; }
26
- for (const name of entries) {
27
- if (SKIP_DIRS.has(name)) continue;
28
- const full = join(dir, name);
29
- let st = null;
30
- try { st = statSync(full); } catch { continue; }
31
- if (st.isDirectory()) collectFiles(root, exts, full, out);
32
- else if (exts.some((x) => name.endsWith(x))) out.push(relative(root, full).replace(/\\/g, '/'));
33
- }
34
- return out;
35
- }
36
-
37
- /** 解析命令行参数。 */
38
- function parseArgs(argv) {
39
- const args = { exts: DEFAULT_EXTS, json: false, unused: false, top: 8 };
40
- const positional = [];
41
- for (let i = 0; i < argv.length; i++) {
42
- const a = argv[i];
43
- if (a === '--json') args.json = true;
44
- else if (a === '--unused') args.unused = true;
45
- else if (a === '--top') args.top = Number(argv[++i] || 8);
46
- else if (a === '--ext') args.exts = String(argv[++i] || '').split(',').map((s) => s.trim()).filter(Boolean);
47
- else if (a.startsWith('--')) throw new Error(`未知参数: ${a}`);
48
- else positional.push(a);
49
- }
50
- args.root = positional[0];
51
- return args;
52
- }
53
-
54
- const args = parseArgs(process.argv.slice(2));
55
- if (!args.root) {
56
- console.error('用法: node scripts/symbol-index.mjs <仓库目录> [--json] [--unused] [--top N] [--ext .js,.mjs]');
57
- process.exit(2);
58
- }
59
- const root = resolve(args.root);
60
- const files = collectFiles(root, args.exts);
61
- const index = buildSymbolIndex(files, { readFile: (rel) => readFileSync(join(root, rel), 'utf8') });
62
- const unused = unusedExportCandidates(index);
63
-
64
- if (args.json) {
65
- console.log(JSON.stringify({
66
- root, stats: index.stats, summary: indexSummary(index),
67
- edges: index.edges, unresolved: index.unresolved, unusedExports: unused,
68
- }, null, 2));
69
- } else {
70
- console.log(`仓库: ${root}`);
71
- console.log(indexSummary(index));
72
- console.log(`排除的成员调用: ${index.stats.skippedMemberCalls}(x.y() 这类不经符号索引解析)`);
73
- const byReason = {};
74
- for (const u of index.unresolved) byReason[u.reason] = (byReason[u.reason] || 0) + 1;
75
- console.log(`未解析构成: ${JSON.stringify(byReason)}`);
76
- const top = index.edges.filter((e) => e.via === 'import').slice(0, args.top);
77
- if (top.length) {
78
- console.log(`跨文件调用边(前 ${top.length} 条):`);
79
- for (const e of top) console.log(` ${e.from}:${e.line} → ${e.to}`);
80
- }
81
- if (args.unused) {
82
- console.log(`未使用导出候选(${unused.length} 个,动态访问/外部引用无法静态判定,仅作线索):`);
83
- for (const u of unused.slice(0, args.top * 3)) console.log(` ${u.file}:${u.line} ${u.name}`);
84
- }
85
- }
@@ -1,100 +0,0 @@
1
- /**
2
- * 上下文注入自检脚本(配合 1.5.2 工具探测改上下文注入)
3
- *
4
- * 真实调用 apply() 并触发 agent/pre-step,验证环境信息按上下文注入:
5
- * - 工作区跑:验证接线正确 + 无 DSH 依赖时降级不崩(@deepseek-ai/dsh-llm 解析不到 → 注入跳过)
6
- * - 安装副本跑(profiles/.../node_modules/dsh-git-push):完整验证注入 user 消息
7
- * (工作区目录 + 工具安装路径(实测)+ skill 总入口,source 标记 plugin instructions)
8
- *
9
- * 用法:node scripts/verify-prestep.mjs
10
- * 退出码:0 = 接线与(可注入时)注入全部符合预期;1 = 断言失败
11
- */
12
- import { apply } from '../lib/app/apply.js';
13
- import { setDefineToolOverride } from '../lib/plugin/index.js';
14
-
15
- /** 被验证的宿主事件名(pre-step:上下文注入发生在 agent 回合前)。 */
16
- const PRE_STEP_EVENT = 'agent/pre-step';
17
-
18
- /** 简易断言计数(不引测试框架)。 */
19
- const results = [];
20
- function check(name, ok) { results.push([name, !!ok]); if (!ok) console.log(' ❌', name); }
21
-
22
- // 1) defineTool 喂 mock(工作区无 DSH 依赖;安装副本同样可喂)
23
- setDefineToolOverride((spec) => spec);
24
-
25
- // 2) mock DSH ctx:tools/systemPrompt/webServer 服务 + agent/pre-step 事件捕获
26
- const sections = [];
27
- const events = {};
28
- const registered = [];
29
- const ctx = {
30
- get: (k) => (k === 'log' ? { info: () => {}, warn: (...a) => console.log(' [warn]', ...a) } : undefined),
31
- inject: (keys, fn) => {
32
- if (keys[0] === 'tools') fn({ get: (k) => (k === 'tools' ? { register: (t) => registered.push(t) } : undefined) });
33
- if (keys[0] === 'systemPrompt') fn({ get: (k) => (k === 'systemPrompt' ? { section: (s) => sections.push(s) } : undefined) });
34
- if (keys[0] === 'webServer') fn({ get: (k) => (k === 'webServer' ? { register: () => {} } : undefined) });
35
- },
36
- on: (name, handler) => { events[name] = handler; },
37
- };
38
-
39
- // 3) 真实调用 apply
40
- await apply(ctx, { workspaceRoot: process.cwd() });
41
- setDefineToolOverride(null);
42
-
43
- console.log('== 注册统计 ==');
44
- console.log('systemPrompt sections:', sections.map((s) => s.name).join(', ') || '(空)');
45
- console.log('agent/pre-step 接线:', typeof events[PRE_STEP_EVENT] === 'function' ? '✅ 是' : '❌ 否');
46
- console.log('工具注册数:', registered.length);
47
-
48
- // 环境段不应再注册为 systemPrompt section(迁出)
49
- check('systemPrompt 不含环境段(dsh-git-push-env 已迁出)', !sections.some((s) => s.name === 'dsh-git-push-env'));
50
- check('systemPrompt 保留功能用法段', sections.some((s) => s.name === 'dsh-git-push-usage'));
51
- check('agent/pre-step 已接线', typeof events[PRE_STEP_EVENT] === 'function');
52
- check('工具已注册', registered.length >= 8);
53
-
54
- if (typeof events[PRE_STEP_EVENT] !== 'function') {
55
- console.log('\n❌ 未接线,退出(exit 1)');
56
- process.exit(1);
57
- }
58
-
59
- // 4) 构造「首次 step」decision 并触发 pre-step
60
- const decision = {
61
- kind: 'next',
62
- messages: [{ role: 'user', content: [{ type: 'text', text: '(原有消息)' }] }],
63
- };
64
- const agent = { id: 'verify-agent-1', session: { id: 'verify-session' } };
65
- const first = await events[PRE_STEP_EVENT]({ agent, signal: undefined }, async () => decision);
66
- const count1 = first.messages.length;
67
- const injected = count1 > 1 ? first.messages[count1 - 1] : null;
68
-
69
- console.log('\n== 首次触发 ==');
70
- check('首次触发追加 1 条注入消息', count1 === 2);
71
- if (injected) {
72
- check('注入消息 role=user', injected.role === 'user');
73
- check('注入消息 source 标记(plugin/dsh-git-push/instructions)',
74
- injected.source?.kind === 'plugin' && injected.source?.plugin === 'dsh-git-push' && injected.source?.form === 'instructions');
75
- }
76
-
77
- // 5) 再次触发同一 agent:WeakSet 防重复,不应再追加
78
- const second = await events[PRE_STEP_EVENT]({ agent, signal: undefined }, async () => decision);
79
- check('二次触发不重复注入(回到原 1 条)', second.messages.length === 1);
80
-
81
- // 6) 注入正文内容校验(注入成功时)
82
- if (injected) {
83
- const text = injected.content?.[0]?.text || '';
84
- console.log('\n== 注入上下文正文 ==\n----------------------------------------');
85
- console.log(text);
86
- console.log('----------------------------------------');
87
- check('含工作区根目录', /工作区根目录/.test(text));
88
- check('含当前工作目录 cwd', /当前工作目录 cwd/.test(text));
89
- check('含工具安装路径', /工具:/.test(text));
90
- check('含 git 实测路径', /git=/.test(text));
91
- check('含 skill 总入口', /skills/.test(text));
92
- } else {
93
- console.log('\n(未注入:当前运行环境无 @deepseek-ai/dsh-llm 依赖,属预期降级;')
94
- console.log(' 在安装副本 profiles/.../node_modules/dsh-git-push 下运行可完整验证注入)');
95
- }
96
-
97
- // 7) 汇总
98
- const failed = results.filter(([, ok]) => !ok).length;
99
- console.log(`\n== 结果:${results.length - failed}/${results.length} 通过 ==`);
100
- process.exit(failed ? 1 : 0);
@@ -1,58 +0,0 @@
1
- ---
2
- name: audit-rule-authoring
3
- description: 给 dsh-git-push 审计引擎新增规则的要点与坑:allow/deny 两种精筛语义、allow 语义下必须自查注释与字符串、判据收窄前先在自己仓库量命中量、用真实样本当回归测试、诚实标注代理特征。处理「新增审计规则」「性能规则」「规则误报太多」「astConfirmKind」类场景时加载。
4
- whenToUse: 给本插件(或同类规则引擎)新增/调整审计规则时;规则误报或漏报排查时。
5
- generatedBy: deepseek-v4-flash(2026-10-08)
6
- ---
7
-
8
- # 审计规则编写要点(dsh-git-push)
9
-
10
- > **先记住我**:任何会话开始前,先读用户档案 `ai-work-archive/skills/remember-me.md`(优先级最高)。
11
- > 本 skill 为**插件相关**,权威位置:插件项目 `skills/dev/`。
12
-
13
- ## 一、规则形态(沿用既有架构,不另造机制)
14
-
15
- | 层 | 文件 | 职责 |
16
- |---|---|---|
17
- 规则声明 | `lib/audit-rules/audit-rules-<槽位>.yml` | id / category / severity / exts / patterns / mitigation |
18
- AST 精筛 | `lib/ast/<模块>.js` | 提供「命中行号集合」的判定函数(如 `loopBodyLines`) |
19
- 引擎派发 | `lib/checks/regex.js` | 按 `rule.astConfirmKind` 取精筛集合 |
20
- 取值出口 | `lib/checks/common.js` | 统一导出精筛集合取值函数(约定:都从这里取) |
21
-
22
- ## 二、两种精筛语义(关键)
23
-
24
- | 语义 | 含义 | 典型用法 |
25
- |---|---|---|
26
- `deny` | 集合内的行**豁免** | 受控小文件读取不算 memory-bomb |
27
- `allow` | **只有**集合内的行才报 | token 级短名、循环体内的命中 |
28
-
29
- ## 三、坑(都踩过)
30
-
31
- 1. **allow 语义会跳过引擎的通用 `codeFilter`** → 注释/字符串里的示例**不会被自动过滤**。
32
- 实测:规则说明注释里写了 `Array.from(x.values())` 示例(恰在 `for` 循环体内),被自己的规则命中。
33
- → 用 `tokenize()` 做 **token 级排除**:同行存在 `comment`/`str`/`tmpl` 且文本包含命中串则不算命中。
34
- 2. **判据先宽后窄必须量化**:第一版规则在我们仓库炸出 **218 处**(`log/push/emit/readFile` 这类
35
- 重复调用是有意为之)→ 收窄到「查询/解析类函数名」后 **4 处**。
36
- → 纪律:**新规则提交前先在自己仓库跑一遍数命中量**,量级不合理先收窄。
37
- 3. **edit 锚点行会被自己吃掉**:把「函数注释头」当锚点替换 → 留下孤儿注释 → `SyntaxError`。
38
- → 凡 edit 后立刻 `node --check`;「在某行前插入」时锚点行必须原样出现在新内容里。
39
- 4. **不要用「同一函数内占比高」证明「某几行是元凶」** → 改完复测才作数(见 `perf-diagnosis-method`)。
40
-
41
- ## 四、测试写法
42
-
43
- - **用真实样本当回归测试**:把外部真实项目里的问题片段(如 `symbol-table.ts` 的循环内物化结构)
44
- 写成 fixture 字符串,断言「必须命中」;再配「循环外/实参不同/注释里」的负样本断言「不报」。
45
- - 端到端再补一条:`checkRegexRules({ file, text, rules: [<规则对象>] })` 断言命中数与规则 id
46
- (规则对象用 `subPatterns: [{ regex, message }]` 形态,`patterns: [{regex}]` 会被引擎当 RegExp 用而报错)。
47
-
48
- ## 五、诚实标注
49
-
50
- 规则是**代理特征**,不是判决器:
51
- - 「循环内全量物化」能静态判 → 可作规则;
52
- - 「入参部分重叠的重复调用」「函数是否真的贵」→ 静态判不出来,只能靠运行时探针;
53
- - 结论里要写清「本规则抓什么、抓不到什么」,避免使用者误以为规则=全知。
54
-
55
- ## 配套
56
-
57
- - `perf-diagnosis-method`(性能定位与等价性验证)、`diagnostic-to-code-rule`(诊断转规则)、
58
- - `code-detailed-comments`(注释写为什么)、`test-design-norms`(测试路径与隔离规范)。
@@ -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