dsh-better-debug 0.2.4 → 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 +27 -4
  2. package/README.md +23 -4
  3. package/package.json +4 -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.4/dsh-better-debug-0.2.4.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,9 +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
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
306
307
  npm run verify # all of the above (with syntax checks)
307
308
  ```
308
309
 
@@ -351,7 +352,28 @@ Windows dev machine and CI supplies the fourth. The assertions no longer hard-co
351
352
  `samePath` / `sameDirs` compare per platform, and expectations are written in their **original
352
353
  case** (`C:/Users/u/...`, `/home/u/projB`).
353
354
 
354
- The rest of the same family, all fixed in v0.2 / v0.2.1 / v0.2.2 / v0.2.3:
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:
355
377
 
356
378
  | Symptom | Root cause | Now |
357
379
  | --- | --- | --- |
@@ -365,6 +387,7 @@ The rest of the same family, all fixed in v0.2 / v0.2.1 / v0.2.2 / v0.2.3:
365
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 |
366
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 |
367
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 |
368
391
 
369
392
  **Case folding is decided per platform** (`CASE_INSENSITIVE`): only on `win32` / `darwin`.
370
393
  The cost of folding wrong is asymmetric — not folding when you should under-reports, folding
@@ -372,7 +395,7 @@ when you should not **over-reports** (crying wolf), and over-reporting is the on
372
395
  gate must not make. A case-sensitive APFS volume on macOS under-reports a little, which is
373
396
  still the safe direction.
374
397
 
375
- `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.
376
399
 
377
400
  ## Known boundaries
378
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.4/dsh-better-debug-0.2.4.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,9 +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
369
  npm run test:linux # 再把上面两套用 Linux 平台语义(不折叠大小写)跑一遍
370
+ npm run test:slow # 把落盘拖慢 400ms,验证「等条件读日志」而不是等时长
370
371
  npm run verify # 上面全部(含语法检查)
371
372
  ```
372
373
 
@@ -415,7 +416,24 @@ ubuntu / windows / macos × node 20 / 22 / 24 上跑 `npm run verify`,所以
415
416
  Linux + posix 由 CI 补。断言里因此不再写死某种大小写,而是用 `samePath` / `sameDirs`
416
417
  按平台比较,期望值用**原始大小写**书写(`C:/Users/u/...`、`/home/u/projB`)。
417
418
 
418
- 同一类问题的其余各处,都在 v0.2 / v0.2.1 / v0.2.2 / v0.2.3 修掉了:
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 修掉了:
419
437
 
420
438
  | 症状 | 根因 | 现在 |
421
439
  | --- | --- | --- |
@@ -429,12 +447,13 @@ Linux + posix 由 CI 补。断言里因此不再写死某种大小写,而是
429
447
  | 在兄弟目录跑测试,把这个目录的盲改计数洗白了 | `measureDirs` 把 `cd <dir>` 当文件取父目录(`cd ~/projB` → `~`) | 认 `cd` 形式,那段路径按目录处理 |
430
448
  | 面板永远红着脸说「插件当前被关闭」,而它明明在跑 | 横幅数的是**整份日志**里的 `disabled` / `panel failed`,历史里挂过一次就永久算「现在坏了」 | 横幅只认最后一次 `apply` 之后(`log.current`),历史单独的个数写在页脚 |
431
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 当回归防线 |
432
451
 
433
452
  **大小写折叠按平台判**(`CASE_INSENSITIVE`):只在 `win32` / `darwin` 上折叠。折叠错了的
434
453
  后果不对称——该折叠却不折叠是漏报,不该折叠却折叠是**误报**(狼来了),后者才是这道闸门
435
454
  最不能犯的错。macOS 上装了区分大小写的 APFS 会少报一点,仍然是安全方向。
436
455
 
437
- `test/panel.mjs` 覆盖 **40 个用例**:带引号与转义的字段切分、六种行型解析(`inject` / `outcome` /
456
+ `test/panel.mjs` 覆盖 **40 个用例**(慢盘轮 41 条:多的是那条「替身确实被用到」的自检——hook 没生效时它会红,避免整轮在测空气):带引号与转义的字段切分、六种行型解析(`inject` / `outcome` /
438
457
  `change` / `measure` / `arm` / `panel-failed`)、`charsFor` 与真实文案长度零漂移(6 组信号组合)、
439
458
  `worstStreak` 在日志→解析→聚合→面板全链路保留、`suppress` 与 `arm` 行可解析且不计入触发、
440
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.4",
3
+ "version": "0.2.5",
4
4
  "description": "卡住闸门的代码化:同一文件连续盲改 / 同一操作重复报错 / 改完没有回路又动手,命中就在下一步注入一次提醒,逼出一条几秒能跑的反馈回路。",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
@@ -49,11 +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 && node --check test/linux/register.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
55
  "test:linux": "node --import ./test/linux/register.mjs test/sim.mjs && node --import ./test/linux/register.mjs test/panel.mjs",
56
- "test": "npm run test:unit && npm run test:posix && npm run test:linux",
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",
57
58
  "verify": "npm run check && npm test"
58
59
  }
59
60
  }