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.
Files changed (3) hide show
  1. package/README.en.md +45 -5
  2. package/README.md +38 -5
  3. 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.3/dsh-better-debug-0.2.3.tgz
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 is a `test:posix` pass
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
- The rest of the same family, all fixed in v0.2 / v0.2.1 / v0.2.2 / v0.2.3:
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**: 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.
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.3/dsh-better-debug-0.2.3.tgz
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
- 同一类问题的其余各处,都在 v0.2 / v0.2.1 / v0.2.2 / v0.2.3 修掉了:
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 个用例**:带引号与转义的字段切分、六种行型解析(`inject` / `outcome` /
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",
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": "npm run test:unit && npm run test:posix",
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
  }