dsh-better-debug 0.2.3 → 0.2.5
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.en.md +45 -5
- package/README.md +38 -5
- package/package.json +5 -3
package/README.en.md
CHANGED
|
@@ -184,7 +184,7 @@ dsh plugin add dsh-better-debug
|
|
|
184
184
|
**Or from the Release tarball (pnpm treats it as a normal package):**
|
|
185
185
|
|
|
186
186
|
```bash
|
|
187
|
-
dsh plugin add https://github.com/Leonlee114514/dsh-better-debug/releases/download/v0.2.
|
|
187
|
+
dsh plugin add https://github.com/Leonlee114514/dsh-better-debug/releases/download/v0.2.5/dsh-better-debug-0.2.5.tgz
|
|
188
188
|
```
|
|
189
189
|
|
|
190
190
|
(Both install the same package: the npm tarball is byte-identical to the Release asset.
|
|
@@ -300,8 +300,10 @@ Not writing a file was the v0.1 default, and the cost was new users installing i
|
|
|
300
300
|
```bash
|
|
301
301
|
node --check lib/index.js && node --check lib/panel.js && node --check lib/text.js && node --check client.js
|
|
302
302
|
node test/sim.mjs # 46 cases: gate semantics + portability
|
|
303
|
-
node test/panel.mjs # 40 cases: log parsing, aggregation, generation scoping, instrumentation
|
|
303
|
+
node test/panel.mjs # 40 cases: log parsing, aggregation, generation scoping, instrumentation (41 under test:slow)
|
|
304
304
|
npm run test:posix # re-runs both suites under POSIX path semantics
|
|
305
|
+
npm run test:linux # re-runs both suites under Linux platform semantics (no case folding)
|
|
306
|
+
npm run test:slow # slows log writes to 400ms, proving reads wait on a condition, not a duration
|
|
305
307
|
npm run verify # all of the above (with syntax checks)
|
|
306
308
|
```
|
|
307
309
|
|
|
@@ -318,7 +320,7 @@ Semantics (each with a positive and a negative):
|
|
|
318
320
|
|
|
319
321
|
**No DSH runtime required** — run it first after any change.
|
|
320
322
|
|
|
321
|
-
### Why there
|
|
323
|
+
### Why there are `test:posix` and `test:linux` passes
|
|
322
324
|
|
|
323
325
|
Every path in `test/sim.mjs` is written in Windows dialect (`C:/work/...`). The suite still
|
|
324
326
|
runs on a Linux box, but it exercises a *different* set of semantics — which was exactly a
|
|
@@ -335,7 +337,43 @@ and then **re-runs both suites unchanged** — so a Windows dev machine reproduc
|
|
|
335
337
|
semantics. CI runs `npm run verify` on ubuntu / windows / macos × node 20 / 22 / 24, so this
|
|
336
338
|
cannot quietly regress. (24 is not padding: the desktop build runs Electron's bundled node 24.)
|
|
337
339
|
|
|
338
|
-
|
|
340
|
+
`test:linux` covers the other axis. `test:posix` swaps only `node:path` and **does not fake
|
|
341
|
+
`process.platform`**, so `CASE_INSENSITIVE` stays `true` in that pass. The case-folding branch
|
|
342
|
+
never executes on a Windows dev machine — until 2026-11-14, when real ubuntu CI turned the two new
|
|
343
|
+
v0.2.2 assertions red: they hard-coded lowercase expectations (`c:/users/u/...`,
|
|
344
|
+
`['/home/u/projb']`), while Linux keeps the case you wrote. The defect was not in the code under
|
|
345
|
+
test but **in assertions that had absorbed this machine's platform** — they were testing "passes on
|
|
346
|
+
Windows".
|
|
347
|
+
|
|
348
|
+
`test/linux/register.mjs` overrides `process.platform` to `linux` and touches nothing else (it is
|
|
349
|
+
a getter, so it needs `Object.defineProperty`; a plain assignment is silently ignored). With the
|
|
350
|
+
two axes separated, three of the four "path dialect × case sensitivity" combinations run on a
|
|
351
|
+
Windows dev machine and CI supplies the fourth. The assertions no longer hard-code a case:
|
|
352
|
+
`samePath` / `sameDirs` compare per platform, and expectations are written in their **original
|
|
353
|
+
case** (`C:/Users/u/...`, `/home/u/projB`).
|
|
354
|
+
|
|
355
|
+
### Why there is a `test:slow` pass
|
|
356
|
+
|
|
357
|
+
The third kind of "green here, red on a real machine" is not platform semantics but **timing**.
|
|
358
|
+
The plugin writes log lines with `void record(...)` — deliberately not awaited, because one log
|
|
359
|
+
line must not slow the agent down. The price is that "has it been written yet" is always a race
|
|
360
|
+
when a test reads the log back.
|
|
361
|
+
|
|
362
|
+
Real CI (`windows-latest` + node 24) went red exactly that way on 2026-11-14: the `inject`,
|
|
363
|
+
`outcome` and `change` lines had landed, `measure` was still queued, and the assertion reported
|
|
364
|
+
`no measure line` — which looks like broken instrumentation but is just an **early read**. The fix
|
|
365
|
+
is not raising `sleep` from 120ms to 500ms (that only rolls the dice again) but replacing "wait a
|
|
366
|
+
duration" with "wait for a condition": `readLogWhenReady()` re-reads every 10ms until the wanted
|
|
367
|
+
line kinds exist, and on timeout prints **which lines are missing**, so the failure points at the
|
|
368
|
+
real gap.
|
|
369
|
+
|
|
370
|
+
`test/slow` makes that timing deterministic: a `registerHooks` resolver swaps
|
|
371
|
+
`node:fs/promises` for a stand-in whose `appendFile` is 400ms slower (`BD_SLOW_MS` adjustable).
|
|
372
|
+
Any "wait a fixed duration" read goes red every time; a "wait for the condition" read stays green
|
|
373
|
+
no matter how slow. It is a regression guard, not a benchmark. On `node < 22.15` there is no
|
|
374
|
+
`registerHooks`, so this pass skips itself — the same two-channel strategy as `test:posix`.
|
|
375
|
+
|
|
376
|
+
The rest of the same family, all fixed in v0.2 / v0.2.1 / v0.2.2 / v0.2.3 / v0.2.4 / v0.2.5:
|
|
339
377
|
|
|
340
378
|
| Symptom | Root cause | Now |
|
|
341
379
|
| --- | --- | --- |
|
|
@@ -348,6 +386,8 @@ The rest of the same family, all fixed in v0.2 / v0.2.1 / v0.2.2 / v0.2.3:
|
|
|
348
386
|
| `a1.js` and `a2.js` are treated as the same place | normalisation replaced every digit in the path with `<n>`; only line/column should go | only the trailing `(:\d+)+$` is stripped |
|
|
349
387
|
| Running tests in a sibling directory washed out this directory's blind-edit count | `measureDirs` treated `cd <dir>` as a file and took its parent (`cd ~/projB` → `~`) | `cd` is recognised; that segment is a directory |
|
|
350
388
|
| The panel kept showing "the plugin is currently disabled" while it was clearly running | the banner counted `disabled` / `panel failed` over the **whole log**, so one historical failure counted as "broken now" forever | the banner only reads the generation after the last `apply` (`log.current`); history is reported separately in the footer |
|
|
389
|
+
| New assertions were green on Windows and red on real Linux CI | they hard-coded the `CASE_INSENSITIVE` fold result; `test:posix` swaps `node:path` but not `platform`, so that branch never ran here | the `test:linux` pass overrides `process.platform`, and assertions compare through `samePath` per platform |
|
|
390
|
+
| The same suite is 40/40 here and 38/40 on `windows-latest` + node 24 | the test used a fixed `sleep` to wait for log writes; the plugin deliberately does `void record(...)` without awaiting, so on a slow disk `measure` was read before it landed | log reads now wait on a condition (`readLogWhenReady`), and `test:slow` slows writes by 400ms as a regression guard |
|
|
351
391
|
|
|
352
392
|
**Case folding is decided per platform** (`CASE_INSENSITIVE`): only on `win32` / `darwin`.
|
|
353
393
|
The cost of folding wrong is asymmetric — not folding when you should under-reports, folding
|
|
@@ -355,7 +395,7 @@ when you should not **over-reports** (crying wolf), and over-reporting is the on
|
|
|
355
395
|
gate must not make. A case-sensitive APFS volume on macOS under-reports a little, which is
|
|
356
396
|
still the safe direction.
|
|
357
397
|
|
|
358
|
-
`test/panel.mjs` covers **40 cases
|
|
398
|
+
`test/panel.mjs` covers **40 cases** (41 under `test:slow`; the extra one asserts the slow shim is actually in use, so that pass can never be testing nothing): quoted and escaped field splitting; six line kinds (`inject` / `outcome` / `change` / `measure` / `arm` / `panel-failed`); zero drift between `charsFor` and the real text length across 6 signal combinations; `worstStreak` preserved along log→parse→aggregate→panel; `suppress` and `arm` lines parsed and not counted as fires; the aggregated `firstAction` / `turned` / `measures`; **assertions that v0.1's field names `changed` / `changedRate` / `outcomes` must not come back**; thresholds from the last `apply`; empty logs and bad lines not throwing; and an end-to-end run that really calls `apply()`, walks one turn, and reads the log back to assert `inject` carries `inj=`, `outcome` carries `before=write`, `measure ok=false exit=1`, and `change` is written and aggregated. Generation scoping has its own group: failures in the history with a clean generation after the last `apply` must leave `log.current` at zero and keep the banner quiet; a failure *after* the last `apply` must light it; a log with no `apply` line at all gives `markers=0`, and the panel says it only has a fragment rather than claiming health. **The page itself is asserted too** — the test reads `web/index.html` and checks the banner consumes `log.current` and no whole-log branch survived.
|
|
359
399
|
|
|
360
400
|
## Known boundaries
|
|
361
401
|
|
package/README.md
CHANGED
|
@@ -222,7 +222,7 @@ dsh plugin add dsh-better-debug
|
|
|
222
222
|
**或者从 Release tarball 装(pnpm 会把它当普通包装进 profile):**
|
|
223
223
|
|
|
224
224
|
```bash
|
|
225
|
-
dsh plugin add https://github.com/Leonlee114514/dsh-better-debug/releases/download/v0.2.
|
|
225
|
+
dsh plugin add https://github.com/Leonlee114514/dsh-better-debug/releases/download/v0.2.5/dsh-better-debug-0.2.5.tgz
|
|
226
226
|
```
|
|
227
227
|
|
|
228
228
|
(两条装的是同一个包:npm 上的 tarball 与 Release 资产逐字节相同。走 npm 的好处是
|
|
@@ -364,8 +364,10 @@ bundle 层按原样加载」。也就是说:**写了 config,用户点「启
|
|
|
364
364
|
```bash
|
|
365
365
|
node --check lib/index.js && node --check lib/panel.js && node --check lib/text.js && node --check client.js
|
|
366
366
|
node test/sim.mjs # 46 个用例:闸门语义 + 可移植性
|
|
367
|
-
node test/panel.mjs # 40
|
|
367
|
+
node test/panel.mjs # 40 个用例:日志解析、聚合、世代判定、埋点落盘(慢盘轮多 1 条自检,41)
|
|
368
368
|
npm run test:posix # 把上面两套用 POSIX 路径语义再跑一遍
|
|
369
|
+
npm run test:linux # 再把上面两套用 Linux 平台语义(不折叠大小写)跑一遍
|
|
370
|
+
npm run test:slow # 把落盘拖慢 400ms,验证「等条件读日志」而不是等时长
|
|
369
371
|
npm run verify # 上面全部(含语法检查)
|
|
370
372
|
```
|
|
371
373
|
|
|
@@ -387,7 +389,7 @@ npm run verify # 上面全部(含语法检查)
|
|
|
387
389
|
|
|
388
390
|
**不依赖 DSH 运行时**,改动后先跑它。
|
|
389
391
|
|
|
390
|
-
### 为什么有 `test:posix`
|
|
392
|
+
### 为什么有 `test:posix` 与 `test:linux` 两轮
|
|
391
393
|
|
|
392
394
|
`test/sim.mjs` 里的路径全是 `C:/work/...` 这种 Windows 方言。它在一台 Linux 机器上照样
|
|
393
395
|
能跑,但跑的是**另一套语义**——这正是 v0.2 之前的一个真事故:
|
|
@@ -402,7 +404,36 @@ npm run verify # 上面全部(含语法检查)
|
|
|
402
404
|
ubuntu / windows / macos × node 20 / 22 / 24 上跑 `npm run verify`,所以这条不会退回去。
|
|
403
405
|
(24 不是凑数:桌面版 DSH 跑的是 Electron 内置的 node 24。)
|
|
404
406
|
|
|
405
|
-
|
|
407
|
+
`test:linux` 补的是另一根轴。`test:posix` 只换 `node:path`,**不伪造 `process.platform`**,
|
|
408
|
+
所以那一轮里 `CASE_INSENSITIVE` 仍然是 `true`。大小写折叠这条分支因此在本机永远不执行——
|
|
409
|
+
直到 2026-11-14,真机 ubuntu CI 把 v0.2.2 的两组新断言打红:期望值写死成小写
|
|
410
|
+
(`c:/users/u/...`、`['/home/u/projb']`),而 Linux 上路径区分大小写、原样保留大小写。
|
|
411
|
+
根因不在被测代码,在**断言本身也沾了本机平台**——它测的是「Windows 上通过」。
|
|
412
|
+
|
|
413
|
+
`test/linux/register.mjs` 只把 `process.platform` 覆盖成 `linux`(它是 getter,必须
|
|
414
|
+
`Object.defineProperty`;直接赋值会被静默忽略),不碰 path 模块。两轴分开之后,
|
|
415
|
+
「path 方言 × 大小写敏感」四种组合里有三种能在 Windows 开发机上跑到,剩下的
|
|
416
|
+
Linux + posix 由 CI 补。断言里因此不再写死某种大小写,而是用 `samePath` / `sameDirs`
|
|
417
|
+
按平台比较,期望值用**原始大小写**书写(`C:/Users/u/...`、`/home/u/projB`)。
|
|
418
|
+
|
|
419
|
+
### 为什么有 `test:slow` 这一轮
|
|
420
|
+
|
|
421
|
+
第三类「本机绿、真机红」不是平台语义,是**时序**。插件写日志用的是
|
|
422
|
+
`void record(...)`——刻意不 `await`,因为不能因为写一行日志就拖慢 agent 每一步。
|
|
423
|
+
代价是:测试读回日志时,「写完了没有」永远是个竞态。
|
|
424
|
+
|
|
425
|
+
2026-11-14 的真机 CI(`windows-latest` + node 24)正是这样红的:`inject` / `outcome` /
|
|
426
|
+
`change` 三行都落盘了,`measure` 还在队列里,断言报 `no measure line`——看起来像埋点坏了,
|
|
427
|
+
其实只是**读早了**。修法不是把 `sleep` 从 120ms 加到 500ms(那只是把骰子换个面),
|
|
428
|
+
而是把「等时长」换成「等条件」:`readLogWhenReady()` 每 10ms 读一次,直到目标行型齐全,
|
|
429
|
+
超时则把**缺哪一行**打印出来,让失败信息指向真正的缺口。
|
|
430
|
+
|
|
431
|
+
`test/slow` 把那个时序放大到必然发生:`registerHooks` 把 `node:fs/promises` 换成
|
|
432
|
+
`appendFile` 慢 400ms 的替身(`BD_SLOW_MS` 可调)。于是任何「等固定时长」的写法都会
|
|
433
|
+
稳定红,而「等条件」的写法不管慢多少都绿。这是回归防线,不是性能测试。
|
|
434
|
+
`node < 22.15` 没有 `registerHooks`,这一轮自动跳过——与 `test:posix` 的两通道策略一致。
|
|
435
|
+
|
|
436
|
+
同一类问题的其余各处,都在 v0.2 / v0.2.1 / v0.2.2 / v0.2.3 / v0.2.4 / v0.2.5 修掉了:
|
|
406
437
|
|
|
407
438
|
| 症状 | 根因 | 现在 |
|
|
408
439
|
| --- | --- | --- |
|
|
@@ -415,12 +446,14 @@ ubuntu / windows / macos × node 20 / 22 / 24 上跑 `npm run verify`,所以
|
|
|
415
446
|
| `a1.js` 与 `a2.js` 被当成同一处 | 归一化把路径里每个数字都换成 `<n>`,只该剥行号列号 | 只剥末尾 `(:\d+)+$` |
|
|
416
447
|
| 在兄弟目录跑测试,把这个目录的盲改计数洗白了 | `measureDirs` 把 `cd <dir>` 当文件取父目录(`cd ~/projB` → `~`) | 认 `cd` 形式,那段路径按目录处理 |
|
|
417
448
|
| 面板永远红着脸说「插件当前被关闭」,而它明明在跑 | 横幅数的是**整份日志**里的 `disabled` / `panel failed`,历史里挂过一次就永久算「现在坏了」 | 横幅只认最后一次 `apply` 之后(`log.current`),历史单独的个数写在页脚 |
|
|
449
|
+
| 新加的用例在 Windows 上全绿,真机 Linux CI 全红 | 断言把 `CASE_INSENSITIVE` 的折叠结果写死了;`test:posix` 只换 `node:path`、不伪造 `platform`,那条分支本机永不执行 | `test:linux` 轮覆盖 `process.platform`,断言改用 `samePath` 按平台比 |
|
|
450
|
+
| 同一份用例在本机 40/40,`windows-latest` + node 24 上 38/40 | 测试用固定 `sleep` 等日志落盘;插件刻意 `void record(...)` 不 `await`,慢盘上 `measure` 行还没写完就读了 | 读日志改成等条件(`readLogWhenReady`),并新增 `test:slow` 把落盘拖慢 400ms 当回归防线 |
|
|
418
451
|
|
|
419
452
|
**大小写折叠按平台判**(`CASE_INSENSITIVE`):只在 `win32` / `darwin` 上折叠。折叠错了的
|
|
420
453
|
后果不对称——该折叠却不折叠是漏报,不该折叠却折叠是**误报**(狼来了),后者才是这道闸门
|
|
421
454
|
最不能犯的错。macOS 上装了区分大小写的 APFS 会少报一点,仍然是安全方向。
|
|
422
455
|
|
|
423
|
-
`test/panel.mjs` 覆盖 **40
|
|
456
|
+
`test/panel.mjs` 覆盖 **40 个用例**(慢盘轮 41 条:多的是那条「替身确实被用到」的自检——hook 没生效时它会红,避免整轮在测空气):带引号与转义的字段切分、六种行型解析(`inject` / `outcome` /
|
|
424
457
|
`change` / `measure` / `arm` / `panel-failed`)、`charsFor` 与真实文案长度零漂移(6 组信号组合)、
|
|
425
458
|
`worstStreak` 在日志→解析→聚合→面板全链路保留、`suppress` 与 `arm` 行可解析且不计入触发、
|
|
426
459
|
聚合出的 `firstAction` / `turned` / `measures`、**断言 v0.1 的旧字段名
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-better-debug",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.5",
|
|
4
4
|
"description": "卡住闸门的代码化:同一文件连续盲改 / 同一操作重复报错 / 改完没有回路又动手,命中就在下一步注入一次提醒,逼出一条几秒能跑的反馈回路。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -49,10 +49,12 @@
|
|
|
49
49
|
"dsh": ">=0.2.1-rc.5"
|
|
50
50
|
},
|
|
51
51
|
"scripts": {
|
|
52
|
-
"check": "node --check lib/index.js && node --check lib/panel.js && node --check lib/text.js && node --check client.js && node --check test/sim.mjs && node --check test/panel.mjs && node --check test/posix/register.mjs && node --check test/posix/hooks.mjs && node --check test/posix/path.mjs",
|
|
52
|
+
"check": "node --check lib/index.js && node --check lib/panel.js && node --check lib/text.js && node --check client.js && node --check test/sim.mjs && node --check test/panel.mjs && node --check test/posix/register.mjs && node --check test/posix/hooks.mjs && node --check test/posix/path.mjs && node --check test/linux/register.mjs && node --check test/slow/register.mjs && node --check test/slow/fs.mjs",
|
|
53
53
|
"test:unit": "node test/sim.mjs && node test/panel.mjs",
|
|
54
54
|
"test:posix": "node --import ./test/posix/register.mjs test/sim.mjs && node --import ./test/posix/register.mjs test/panel.mjs",
|
|
55
|
-
"test": "
|
|
55
|
+
"test:linux": "node --import ./test/linux/register.mjs test/sim.mjs && node --import ./test/linux/register.mjs test/panel.mjs",
|
|
56
|
+
"test:slow": "node --import ./test/slow/register.mjs test/panel.mjs",
|
|
57
|
+
"test": "npm run test:unit && npm run test:posix && npm run test:linux && npm run test:slow",
|
|
56
58
|
"verify": "npm run check && npm test"
|
|
57
59
|
}
|
|
58
60
|
}
|