peaks-loop 4.1.21 → 4.1.23
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/.claude-plugin/marketplace.json +3 -6
- package/CHANGELOG.md +191 -0
- package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
- package/dist/cli/commands/mut-commands-helpers.js +44 -26
- package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
- package/dist/cli/commands/observability-commands-hotspots.js +222 -0
- package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
- package/dist/cli/commands/observability-commands-near-miss.js +105 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
- package/dist/cli/commands/observability-commands-queries.js +88 -47
- package/dist/cli/commands/observability-commands.js +79 -20
- package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
- package/dist/services/artifacts/artifact-prerequisites.js +1 -1
- package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
- package/dist/services/artifacts/prerequisite-path-census.js +79 -0
- package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
- package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
- package/dist/services/artifacts/rd-gate-event.js +211 -0
- package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
- package/dist/services/artifacts/rd-transition-gates.js +65 -24
- package/dist/services/distribution/json-layout.d.ts +20 -0
- package/dist/services/distribution/json-layout.js +195 -0
- package/dist/services/distribution/plugin-manifest.d.ts +31 -2
- package/dist/services/distribution/plugin-manifest.js +40 -4
- package/dist/services/observability/aggregation-types.d.ts +21 -0
- package/dist/services/observability/aggregation.d.ts +12 -2
- package/dist/services/observability/aggregation.js +26 -2
- package/dist/services/observability/compliance-judge.d.ts +77 -0
- package/dist/services/observability/compliance-judge.js +143 -0
- package/dist/services/observability/compliance-spec.d.ts +96 -0
- package/dist/services/observability/compliance-spec.js +29 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
- package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
- package/dist/services/observability/hotspot-attribution-summary.js +74 -0
- package/dist/services/observability/hotspot-rows.d.ts +47 -0
- package/dist/services/observability/hotspot-rows.js +89 -0
- package/dist/services/observability/hotspot-shared.d.ts +212 -0
- package/dist/services/observability/hotspot-shared.js +122 -0
- package/dist/services/observability/hotspot-sources.d.ts +55 -0
- package/dist/services/observability/hotspot-sources.js +142 -0
- package/dist/services/observability/hotspots.d.ts +47 -0
- package/dist/services/observability/hotspots.js +47 -0
- package/dist/services/observability/near-miss-attempts.d.ts +175 -0
- package/dist/services/observability/near-miss-attempts.js +223 -0
- package/dist/services/observability/near-miss-coverage.d.ts +109 -0
- package/dist/services/observability/near-miss-coverage.js +108 -0
- package/dist/services/observability/near-miss-denominator.d.ts +81 -0
- package/dist/services/observability/near-miss-denominator.js +75 -0
- package/dist/services/observability/near-miss-difference.d.ts +98 -0
- package/dist/services/observability/near-miss-difference.js +132 -0
- package/dist/services/observability/near-miss-facts.d.ts +165 -0
- package/dist/services/observability/near-miss-facts.js +101 -0
- package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
- package/dist/services/observability/near-miss-gate-events.js +106 -0
- package/dist/services/observability/near-miss-gates.d.ts +108 -0
- package/dist/services/observability/near-miss-gates.js +135 -0
- package/dist/services/observability/near-miss-records.d.ts +93 -0
- package/dist/services/observability/near-miss-records.js +87 -0
- package/dist/services/observability/near-miss.d.ts +148 -0
- package/dist/services/observability/near-miss.js +196 -0
- package/dist/services/observability/observability-schema.d.ts +17 -2
- package/dist/services/observability/observability-schema.js +21 -1
- package/dist/services/observability/owner-skill-map.d.ts +92 -0
- package/dist/services/observability/owner-skill-map.js +144 -0
- package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
- package/dist/services/observability/report-formatter-hotspots.js +76 -0
- package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
- package/dist/services/observability/report-formatter-near-miss.js +234 -0
- package/dist/services/observability/report-formatter.d.ts +49 -3
- package/dist/services/observability/report-formatter.js +55 -14
- package/dist/services/observability/retro-attribution.d.ts +129 -0
- package/dist/services/observability/retro-attribution.js +134 -0
- package/dist/services/observability/session-metric-rows.d.ts +153 -0
- package/dist/services/observability/session-metric-rows.js +184 -0
- package/package.json +5 -5
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
3
|
"pluginRoot": ".",
|
|
4
|
-
"version": "4.1.
|
|
4
|
+
"version": "4.1.23"
|
|
5
5
|
},
|
|
6
6
|
"plugins": [
|
|
7
7
|
{
|
|
8
8
|
"name": "peaks-loop",
|
|
9
9
|
"description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
|
|
10
|
-
"version": "4.1.
|
|
10
|
+
"version": "4.1.23",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
|
@@ -61,10 +61,7 @@
|
|
|
61
61
|
"mcpServers": {
|
|
62
62
|
"peaks": {
|
|
63
63
|
"command": "peaks",
|
|
64
|
-
"args": [
|
|
65
|
-
"mcp",
|
|
66
|
-
"serve"
|
|
67
|
-
]
|
|
64
|
+
"args": ["mcp", "serve"]
|
|
68
65
|
}
|
|
69
66
|
},
|
|
70
67
|
"skills": [
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,196 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.23 — 2026-10-28(让"技能/门禁到底做了什么"变成可查的数字)
|
|
4
|
+
|
|
5
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何门禁的语义、
|
|
6
|
+
阈值或放行条件;**没有**动事件 schema 的版本号(`schemaVersion` 仍是 `z.literal(1)`);**没有**碰发布流程。
|
|
7
|
+
|
|
8
|
+
**一句话:这一版给 peaks-loop 自己装上了眼睛 —— prereq 事件不再只记"缺了几个"而记"缺的是哪些、归谁",
|
|
9
|
+
门禁层第一次发出自己的判定(pass / block / bypass)并带上当时的声明类型,查询能一次读到全部历史,
|
|
10
|
+
而 `peaks observability near-miss` 第一次能回答"我们过去的『通过』,有多少是靠跳过检查换来的"。**
|
|
11
|
+
|
|
12
|
+
### 1. 头号数字(在本仓库自己的记录历史上实测)
|
|
13
|
+
|
|
14
|
+
| | |
|
|
15
|
+
|---|---|
|
|
16
|
+
| 近失率 | **12.8% = 12 / 94** |
|
|
17
|
+
| 分母 | 94 个**记录了成功的 `verdict-issued` 尝试**的 slice(状态汇总的 `successCount` 是 103,两者对账写进了输出:`94 + 17 − 8 = 103`) |
|
|
18
|
+
| 12 的两种形状 | **11 个「拥有它的角色还没尝试迁移,就宣布通过了」+ 1 个「检查在拒绝时仍然放行」** —— 两种不同的缺陷,不同的修法 |
|
|
19
|
+
| 覆盖率 | **3 个原因类里只有 1 个可观测**(`prereq-skipped` 536 事件 / 94 slice / 12 次近失);`gate-never-evaluated` 与 `tool-blocked` **零事件、`rate: null`** |
|
|
20
|
+
|
|
21
|
+
**这个 12.8% 必须连着覆盖率一起引用。** 两类没数据的原因被写进了每一个界面:CLI 的 `unobservedClasses`
|
|
22
|
+
与逐类 warning、markdown 报告**比率所在的那一行**、以及 spec §2.4.1 的记录表。"未观测"与"观测到 0"
|
|
23
|
+
在输出里是不同的东西 —— 这正是本计划要消灭的那类混淆。
|
|
24
|
+
|
|
25
|
+
**另一件同样重要的事:113 次 prereq 拒绝里,每一次都被补齐后重试通过。** 没有一个是靠跳过检查换来的通过。
|
|
26
|
+
门禁一直在正常工作,只是以前没有人记录它拒绝过什么。
|
|
27
|
+
|
|
28
|
+
### 2. 证据层(不改任何判定,只让判定可见)
|
|
29
|
+
|
|
30
|
+
| 之前 | 之后 |
|
|
31
|
+
|---|---|
|
|
32
|
+
| prereq 事件只记 `missingCount: 3` | 记**清单**:每项带路径、`absent`/`body`、以及**归属技能** |
|
|
33
|
+
| 门禁层**完全不发事件** | 每个判定发一条 `gate` 事件:`gateId` / `phase` / `declaredType` / `outcome`(`pass`\|`block`\|`bypass`)/ `violationKind` / `reason` |
|
|
34
|
+
| 归属只按 `rd/` 前缀整体归给 `peaks-rd` | 更具体的前缀优先 —— `rd/third-party-review-<rid>.md` 现在归 **`peaks-reviewer`** |
|
|
35
|
+
| 汇总把卡在 `qa-handoff` 的 slice 既不算成功也不算失败(**8 个 slice 从账上蒸发**) | 三个桶**划分**全集:`success + fail + stalled === total` |
|
|
36
|
+
| `peaks observability report` 在有 1533 条事件的仓库上打印 `total events 0` | 五个命令都支持 `--all-sessions`;**作用域为空时,输出会告诉你数据在别处**(几个 session、多少条、用哪个开关) |
|
|
37
|
+
| 报告里"近失"只能靠人脑拼 | 报告开头就是"近失"节,含比率、分母及其定义、逐类覆盖率、被标记的 slice 与每键的状态(`refused` / `unattempted`) |
|
|
38
|
+
|
|
39
|
+
### 3. 两个新增测量
|
|
40
|
+
|
|
41
|
+
- **`peaks observability near-miss`** —— 上面那个 12.8%,连同它的覆盖率和分母对账一起输出。
|
|
42
|
+
- **`peaks observability hotspots`** —— 哪个 artifact 被技能反复漏掉。计数被**拆成两组**:
|
|
43
|
+
`observedOmissions`(**确实**观测到缺失)与 `candidateMentions`(v1 历史事件只存计数不存清单,归属是**推出来的**)。
|
|
44
|
+
只有 `confidence: 'exact'` 才算"确实缺失";`inferred` 是"与整个候选集不矛盾",`ambiguous` 是"是其中之一,说不准"。
|
|
45
|
+
拆组是为了让 `count: 91` 永远不会被读成"缺了 91 次"。
|
|
46
|
+
|
|
47
|
+
### 4. 顺带做的两件事
|
|
48
|
+
|
|
49
|
+
- **遵守率(试点)** —— `peaks-rd` 与 `peaks-race-code` 各有一份**可判定的**合规规范,
|
|
50
|
+
`judgeCompliance` 是**纯函数**(文件是否存在由调用方给),判定靠 artifact 契约,**不靠 LLM 猜**。
|
|
51
|
+
- **category 审计** —— 观测 schema 声明的每个 category 现在都写明了它的发射位置、触发条件、
|
|
52
|
+
在记录历史里是否触发过,以及结论(① 条件触发 / ② 需要接线 / ③ 可删)。11 个里有 7 个从未触发,
|
|
53
|
+
包括 `gate` —— 因为这个仓库所有 session 都早于它。
|
|
54
|
+
|
|
55
|
+
### 5. 这一版**没有**交付的东西(如实记录)
|
|
56
|
+
|
|
57
|
+
- **遵守率有裁判,没有读者。** `writeSessionMetricRow` / `readSessionMetricRow` 目前**只有测试在调用** ——
|
|
58
|
+
这一版交付的是**测量机器**,不是合规率的上线。plan 的完成定义里那一项**没有勾**。
|
|
59
|
+
- **`peaks-mut` 的分发缺口。** 它的 `SKILL.md` 在 `src/skills/peaks-mut/`,**不在 npm tarball 的 2935 个文件里**
|
|
60
|
+
(`package.json` 的 `files` 白名单只有 `skills/**`)。所以**装好的 peaks-loop 上,`mut/` 产物没有产出者** ——
|
|
61
|
+
而 `mut/mut-report.json` 是 feature/bugfix/refactor 的 `rd -> qa-handoff` 硬性前置,**那个安装会永远过不了这道门禁**。
|
|
62
|
+
已记录,需要单独一片修。
|
|
63
|
+
- **两个提交的主题与其内容不完全相符** —— `44c0b9b6`("the finding says whether the check was refusing or
|
|
64
|
+
unattempted")实际带了 21 个文件、三个关注点,其中 210 行是热点榜的测试基建;`1005fe00`(`docs(...)`)
|
|
65
|
+
加了 39 行行为测试。两者都是并发提交事故的残留。**内容是对的**,已如实记录;**没有重写历史**。
|
|
66
|
+
- **没有为 `.peaks/_runtime/` 根目录的残留文件加守卫** —— 仓库有仓库根的守卫,没有 runtime 根的。
|
|
67
|
+
|
|
68
|
+
### 6. 顺带修掉的两个"缺失被读成结果"
|
|
69
|
+
|
|
70
|
+
评审复现了它们:
|
|
71
|
+
|
|
72
|
+
- `detail.outcome = 'PASS'`(松散 `z.record` 照收)曾让一次**干净通过**被判成 **近失率 100%**。
|
|
73
|
+
现在 outcome 与 gate id 的词表**只有一份**,从 `rd-gate-event.ts` 导出;读不懂的 outcome 进 `undetermined`,
|
|
74
|
+
而不是"没被评估"。
|
|
75
|
+
- `detail.prereqOk` 是字符串而非布尔时,那个 slice 曾**从分母里消失**("没有通过的 slice",而不是
|
|
76
|
+
"N 个通过的 slice 我们测不了")。现在它落进一个**新的 `unmeasured` 桶** —— 既不算通过、也不算没通过,
|
|
77
|
+
而是被**显式标出**:报告的 `report.unmeasured` 逐条列出并写明记录到的值(例如 `the string "true"`),
|
|
78
|
+
分母侧有 `unmeasuredSliceCount` 与一句"本分母排除了什么"���定义,覆盖率表多一列
|
|
79
|
+
`slices unreadable`,CLI 另有一条 stderr 警告。**读到的判定不可信时,它必须出现在某个地方** ——
|
|
80
|
+
消失就是"缺失被读成结果"。
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
## 4.1.22 — 2026-10-25(把"只测了两个子命令"的漏测补上,把"不是缺陷"的两条说准)
|
|
86
|
+
|
|
87
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何运行时语义、
|
|
88
|
+
**没有**动 mutation 阈值、**没有**碰发布流程;三个代码切片各自只加守卫、**零清单改动**,本切片只做
|
|
89
|
+
**版本锁步 + 生成清单重生成 + 这段 CHANGELOG**。
|
|
90
|
+
|
|
91
|
+
**一句话:`peaks mut` 指向一个**不存在**的 `--test-files` 时,`mut mutants` 过去会**静默回退**到默认发现,
|
|
92
|
+
为一个从未存在过的文件报出**满分 kill rate**(exit 0)—— 而最初的记录只测了 `run` 与 `asserts`、**漏了
|
|
93
|
+
`mutants`**;这一版三个子命令统一 **exit 1 + 具名码 `MUT_TEST_FILE_NOT_FOUND`**。**
|
|
94
|
+
|
|
95
|
+
### 1. 缺陷:`peaks mut` 缺失 `--test-files` 路径时的静默回退(三个子命令这一版统一堵上)
|
|
96
|
+
|
|
97
|
+
同一夹具、同一台机器上的**前后两侧实测**(改前取自 `HEAD` 的隔离树,改后取自本仓库的工作树):
|
|
98
|
+
|
|
99
|
+
| 子命令 | 改前 | 改后 |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| `mut mutants` | **exit 0、写出了报告、killRate 1、mutantsTotal 2** | **exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告** |
|
|
102
|
+
| `mut run` | exit 1 `MUT_FAILED`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
|
|
103
|
+
| `mut asserts` | exit 1 `UNHANDLED_ERROR`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
|
|
104
|
+
|
|
105
|
+
**"静默回退"不是推测,是可比对的 digest。** 改前 `mut mutants` + 缺失文件写出的报告,digest 与
|
|
106
|
+
`mut mutants` + **一个能用的 glob** 写出的报告**完全相同**(两者都是 `339e74cc…`)—— 缺失的路径被
|
|
107
|
+
Stryker 的文件匹配丢掉,vitest runner 跑了项目自己的默认发现,然后为一个**从未存在过的文件**报出了满分。
|
|
108
|
+
改后同一个 glob 仍然 exit 0、digest 仍是 `339e74cc…`(能用的 glob 保持能用),而缺失文件一律 exit 1。
|
|
109
|
+
|
|
110
|
+
改后三个子命令的消息**逐字节相同**,且**只给相对 `--project` 的路径**,并附近邻候选:
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
Test file not found: tests/does-not-exist.test.ts
|
|
114
|
+
Near-miss candidates:
|
|
115
|
+
- tests/add.test.ts
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
**快乐路径没变**:有效测试文件下 `mut run` 的报告 digest 改前改后**都是 `96595ff6…`**(`killRate` 1、
|
|
119
|
+
`mutantsTotal` 2)。守卫 `tests/unit/cli/mut-test-file-not-found.test.ts` **15 个用例全绿**。
|
|
120
|
+
|
|
121
|
+
**这一段要更正的是一条"不可复现"的判断。** 最初的记录写的是"缺失 `--test-files` 路径静默回退默认发现、
|
|
122
|
+
可能报出完美 kill rate"**不可复现** —— 那条判断**只测了 `run` 与 `asserts`**,**漏了 `mutants`**;在
|
|
123
|
+
`mutants` 上它**确实复现**(exit 0 + 满分 kill rate)。本批的三个子命令现在统一成同一个具名码。
|
|
124
|
+
|
|
125
|
+
### 2. 生成的插件清单:`prettier --check` 从 exit 1 变成 exit 0(本次 bump 没有把形状缺陷带回来)
|
|
126
|
+
|
|
127
|
+
清单是**受版本控制的生成产物**(`npm run plugin:manifest`),渲染器过去把**每个**数组都展开,
|
|
128
|
+
所以清单**不是** prettier-clean 的。实测(用仓库自己的 prettier 与仓库自己的 prettier 配置):
|
|
129
|
+
|
|
130
|
+
| | 改前(`HEAD` 的渲染) | 改后(本切片 bump 之后的渲染) |
|
|
131
|
+
|---|---|---|
|
|
132
|
+
| `prettier --check` | **exit 1(不是 prettier-clean)** | **exit 0** |
|
|
133
|
+
| 行数(按换行计数) | 200 | **197** |
|
|
134
|
+
| 行数(按 `split("\n").length`) | 201 | **198** |
|
|
135
|
+
|
|
136
|
+
唯一的变化是 `"args": ["mcp", "serve"]`(4 行 → 1 行)。改前的清单经 prettier 规范化后的输出,
|
|
137
|
+
sha256 是 `849e6168…`,与**本切片 bump 之前**工作树里那份清单(切片 B 的渲染,版本 4.1.21)
|
|
138
|
+
**逐字节相同** —— 说明新的渲染器产出的正是 prettier 自己的形状。本切片 bump 之后的清单
|
|
139
|
+
sha256 是 `fd087f50…`,同样 prettier-clean。
|
|
140
|
+
|
|
141
|
+
**依赖集不变**:根 manifest 的 `dependencies`(12 项)与 `devDependencies`(19 项)与 bump 前**逐字段相同**
|
|
142
|
+
(本切片实测:五个 manifest 各自只有 `version` 一个键变了);`prettier` 仍在 `devDependencies`、
|
|
143
|
+
**不在** `dependencies`(实测 `prettier in dependencies: false`),发布包的运行时依赖集没有变化。
|
|
144
|
+
|
|
145
|
+
**版本戳在两处**:`metadata.version` 与 `plugins[0].version` 都读 `4.1.22`;连跑两次生成**逐字节相同**
|
|
146
|
+
(sha256 `fd087f50…`)。
|
|
147
|
+
|
|
148
|
+
### 3. 包入口不变量(只加守卫,**零清单改动**)
|
|
149
|
+
|
|
150
|
+
根包声明 **1** 个入口(`bin.peaks → ./bin/peaks.js`),`peaks-loop-mut` 声明 **2** 个
|
|
151
|
+
(`exports["."].types`、`exports["."].default`)。守卫 `tests/unit/release/package-entry-points-guard.test.ts`
|
|
152
|
+
**9 passed | 1 skipped**(构建产物在 → 磁盘检查**跑起来**:2 checked、0 skipped)。守卫钉住三条不变量:
|
|
153
|
+
声明的入口必须落在该包自己的 `files` 白名单里;`main` 与 `exports["."].default` 若同时声明必须一致;
|
|
154
|
+
根包**不得**把副作用型 CLI 模块声明成库入口。
|
|
155
|
+
|
|
156
|
+
### 4. 两条必须说准的事(一条"不是缺陷",一条"更正旧判断")
|
|
157
|
+
|
|
158
|
+
**(1)"包缺 `main`"不是缺陷 —— 它不是这次修的东西。** `peaks-loop-mut` 的主入口**已经**由 `exports["."]` 表达
|
|
159
|
+
(`exports["."].default → ./dist/index.js`)。实测(本机 Node v24.12.0):
|
|
160
|
+
|
|
161
|
+
- 一个同时声明 `main` 与 `exports` 的包,被 import 时加载的是 **`exports`** 那个目标(输出 `LOADED:EXPORTS`)
|
|
162
|
+
—— Node 解析 `exports` 优先于 `main`,`main` 被忽略;
|
|
163
|
+
- **`require()` 一个纯 ESM 包在 Node v24.12.0 上是成功的**(实测 `REQUIRE_OK`;`ERR_REQUIRE_ESM`
|
|
164
|
+
只对 Node < 22.12 成立)。所以诚实的理由是**"冗余且会误导"**,而**不是**"无法 require";
|
|
165
|
+
- 根包则**绝不能**加 `main`/`exports`:`dist/cli/index.js` 在**模块顶层**就
|
|
166
|
+
`program.parseAsync(process.argv)`(`src/cli/index.ts:61`),实测**import 它就会把 CLI 跑起来**
|
|
167
|
+
—— 导入过程中就打出了 CLI 的帮助横幅。
|
|
168
|
+
|
|
169
|
+
**(2)"静默回退不可复现"这条旧判断本身不成立 —— 这一版是真的堵上了。** 它在 `mut mutants` 上**确实复现**
|
|
170
|
+
(exit 0 + 满分 kill rate),缺的只是那次测量里的**第三个子命令**。所以这里不是"没有缺陷",而是
|
|
171
|
+
"缺陷是真的、这一版三个子命令统一堵上了"。
|
|
172
|
+
|
|
173
|
+
### 5. 版本号本身
|
|
174
|
+
|
|
175
|
+
| 包 | 从 | 到 |
|
|
176
|
+
|---|---|---|
|
|
177
|
+
| `peaks-loop` | 4.1.21 | **4.1.22** |
|
|
178
|
+
| `peaks-loop-shared` | 0.0.110 | 0.0.111 |
|
|
179
|
+
| `peaks-loop-mut` | 0.1.75 | 0.1.76 |
|
|
180
|
+
| `peaks-loop-shared-channel` | 0.0.78 | 0.0.79 |
|
|
181
|
+
| `peaks-loop-internal-runtime` | 0.0.61 | 0.0.62 |
|
|
182
|
+
|
|
183
|
+
版本号由 `scripts/bump-version.mjs` 产生(不是手打的):根 `4.1.21 → 4.1.22`,四个 workspace 包在同一次
|
|
184
|
+
lockstep 里各 +1,五个 manifest **各自只有 `version` 一个键变了**;`scripts/sync-version.mjs` 把
|
|
185
|
+
`CLI_VERSION` 与 `RUNTIME_VERSION` 写成 `4.1.22`,`node scripts/verify-version-parity.mjs runtime-src`
|
|
186
|
+
**exit 0**。
|
|
187
|
+
|
|
188
|
+
**发布顺序(发版前必须知道)**:`pnpm pack` 会把根包 `workspace:*` 依赖改写成**精确 semver pin**,
|
|
189
|
+
所以 `peaks-loop@4.1.22` 打包后的 manifest 依赖的是 `peaks-loop-mut@0.1.76`、
|
|
190
|
+
`peaks-loop-shared@0.0.111`、`peaks-loop-shared-channel@0.0.79`、`peaks-loop-internal-runtime@0.0.62`
|
|
191
|
+
(实测:从 tarball 里读出的 `package/package.json`)。这四个版本**在 registry 上都不存在**(实测 `E404`),
|
|
192
|
+
所以**这四个包必须先发布**,`peaks-loop@4.1.22` 才能被消费者装上;在它们发布之前,根包是不可安装的。
|
|
193
|
+
|
|
3
194
|
## 4.1.21 — 2026-10-25(把"返工循环"数对,把"没测过"说出来)
|
|
4
195
|
|
|
5
196
|
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改 fail-open 策略、
|
|
@@ -13,7 +13,8 @@
|
|
|
13
13
|
* toolchain must surface a MACHINE-READABLE error code (for example
|
|
14
14
|
* `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
|
|
15
15
|
* non-zero exit code — never `UNHANDLED_ERROR` with a bare
|
|
16
|
-
* "Cannot find package".
|
|
16
|
+
* "Cannot find package". The same rule now covers a missing `--test-files`
|
|
17
|
+
* path (`MUT_TEST_FILE_NOT_FOUND`).
|
|
17
18
|
*/
|
|
18
19
|
import { Command } from 'commander';
|
|
19
20
|
import { type AssertionsReport, type MutationReport, type StrykerInvoker } from 'peaks-loop-mut';
|
|
@@ -75,16 +76,15 @@ export declare function mutErrorCode(err: unknown): string;
|
|
|
75
76
|
/** The human-readable half of the envelope. */
|
|
76
77
|
export declare function mutErrorMessage(err: unknown): string;
|
|
77
78
|
/**
|
|
78
|
-
* Emit the failure envelope on stderr and set a non-zero exit code.
|
|
79
|
-
*
|
|
80
|
-
*
|
|
79
|
+
* Emit the failure envelope on stderr and set a non-zero exit code. Its
|
|
80
|
+
* `data` field carries the machine-readable detail — where an ABSOLUTE path
|
|
81
|
+
* belongs; stdout stays reserved for the `--json` payload (R6).
|
|
81
82
|
*/
|
|
82
83
|
export declare function emitMutError(io: ProgramIO, err: unknown): void;
|
|
83
84
|
/**
|
|
84
85
|
* `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
|
|
85
86
|
* report). One-axis: --session-id required.
|
|
86
|
-
*/
|
|
87
|
-
export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
|
|
87
|
+
*/ export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
|
|
88
88
|
/**
|
|
89
89
|
* `peaks mut mutants` — Stryker only; writes a stub-assertions
|
|
90
90
|
* mut-report.json. One-axis: --session-id required.
|
|
@@ -13,10 +13,11 @@
|
|
|
13
13
|
* toolchain must surface a MACHINE-READABLE error code (for example
|
|
14
14
|
* `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
|
|
15
15
|
* non-zero exit code — never `UNHANDLED_ERROR` with a bare
|
|
16
|
-
* "Cannot find package".
|
|
16
|
+
* "Cannot find package". The same rule now covers a missing `--test-files`
|
|
17
|
+
* path (`MUT_TEST_FILE_NOT_FOUND`).
|
|
17
18
|
*/
|
|
18
19
|
import { Command } from 'commander';
|
|
19
|
-
import { buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
|
|
20
|
+
import { assertTestFilesUsable, buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
|
|
20
21
|
import { printErrorEnvelope } from '../cli-helpers.js';
|
|
21
22
|
/**
|
|
22
23
|
* Fallback code for a mutation failure that carries no named code of its
|
|
@@ -98,18 +99,27 @@ export function mutErrorMessage(err) {
|
|
|
98
99
|
return err instanceof Error ? err.message : String(err);
|
|
99
100
|
}
|
|
100
101
|
/**
|
|
101
|
-
* Emit the failure envelope on stderr and set a non-zero exit code.
|
|
102
|
-
*
|
|
103
|
-
*
|
|
102
|
+
* Emit the failure envelope on stderr and set a non-zero exit code. Its
|
|
103
|
+
* `data` field carries the machine-readable detail — where an ABSOLUTE path
|
|
104
|
+
* belongs; stdout stays reserved for the `--json` payload (R6).
|
|
104
105
|
*/
|
|
105
106
|
export function emitMutError(io, err) {
|
|
106
|
-
|
|
107
|
+
const details = err?.details;
|
|
108
|
+
const data = details && typeof details === 'object' ? details : {};
|
|
109
|
+
printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), data, []);
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Validate `--test-files` BEFORE any Stryker run, scan or report write: a
|
|
113
|
+
* missing path must fail with the named code, never reach the mutation
|
|
114
|
+
* engine. A PATTERN is accepted here — Stryker expands patterns.
|
|
115
|
+
*/
|
|
116
|
+
function assertMutTestFiles(a) {
|
|
117
|
+
assertTestFilesUsable({ project: a.project, testFiles: a.testFiles, allowPatterns: true });
|
|
107
118
|
}
|
|
108
119
|
/**
|
|
109
120
|
* `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
|
|
110
121
|
* report). One-axis: --session-id required.
|
|
111
|
-
*/
|
|
112
|
-
export function buildMutRunCommand(invokeStryker, io) {
|
|
122
|
+
*/ export function buildMutRunCommand(invokeStryker, io) {
|
|
113
123
|
return new Command('run')
|
|
114
124
|
.description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
|
|
115
125
|
.requiredOption('--project <path>', 'project root')
|
|
@@ -121,6 +131,7 @@ export function buildMutRunCommand(invokeStryker, io) {
|
|
|
121
131
|
.option('--json', 'machine-readable output', false)
|
|
122
132
|
.action(async (a) => {
|
|
123
133
|
try {
|
|
134
|
+
assertMutTestFiles(a);
|
|
124
135
|
const { mutation } = await runMutation({
|
|
125
136
|
project: a.project,
|
|
126
137
|
testFiles: a.testFiles,
|
|
@@ -172,6 +183,7 @@ export function buildMutMutantsCommand(invokeStryker, io) {
|
|
|
172
183
|
.option('--json', 'machine-readable output', false)
|
|
173
184
|
.action(async (a) => {
|
|
174
185
|
try {
|
|
186
|
+
assertMutTestFiles(a);
|
|
175
187
|
const { mutation } = await runMutation({
|
|
176
188
|
project: a.project,
|
|
177
189
|
testFiles: a.testFiles,
|
|
@@ -213,24 +225,30 @@ export function buildMutAssertsCommand(io) {
|
|
|
213
225
|
.requiredOption('--out <path>', 'output path for mut-report.json')
|
|
214
226
|
.option('--json', 'machine-readable output', false)
|
|
215
227
|
.action(async (a) => {
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
228
|
+
try {
|
|
229
|
+
assertMutTestFiles(a);
|
|
230
|
+
const assertions = await scanAssertions({
|
|
231
|
+
project: a.project,
|
|
232
|
+
testFiles: a.testFiles
|
|
233
|
+
});
|
|
234
|
+
const report = await buildMutReport({
|
|
235
|
+
inputSig: a.inputSig,
|
|
236
|
+
out: a.out,
|
|
237
|
+
mutation: emptyMutation(),
|
|
238
|
+
assertions
|
|
239
|
+
});
|
|
240
|
+
emitSummary(io, a.json, {
|
|
241
|
+
ok: true,
|
|
242
|
+
sha256: report.sha256,
|
|
243
|
+
passed: report.thresholds.passed,
|
|
244
|
+
path: a.out
|
|
245
|
+
});
|
|
246
|
+
if (!report.thresholds.passed) {
|
|
247
|
+
process.exitCode = 1;
|
|
248
|
+
}
|
|
249
|
+
}
|
|
250
|
+
catch (err) {
|
|
251
|
+
emitMutError(io, err);
|
|
234
252
|
}
|
|
235
253
|
});
|
|
236
254
|
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/cli/commands/observability-commands-hotspots.ts`
|
|
3
|
+
*
|
|
4
|
+
* `peaks observability hotspots` — which artifact does a skill keep failing
|
|
5
|
+
* to deliver, and who owns it.
|
|
6
|
+
*
|
|
7
|
+
* WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
|
|
8
|
+
* That file is at its file-size cap and a later task needs room in it too,
|
|
9
|
+
* so each subcommand's registration lives in its own module and the parent
|
|
10
|
+
* gains one import and one call. The precedent is the sibling split of
|
|
11
|
+
* `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
|
|
12
|
+
*
|
|
13
|
+
* WHY THE REQUEST TYPES ARE RESOLVED HERE. The retro-attribution re-derives
|
|
14
|
+
* a transition's prerequisite list, and the table is indexed by request type —
|
|
15
|
+
* a fact that lives in the request artifact, not in the event stream. The
|
|
16
|
+
* events carry the slice; the request artifact carries the type. So this
|
|
17
|
+
* layer reads the request artifacts and hands the types to the ranking.
|
|
18
|
+
*
|
|
19
|
+
* WHY THE READER IS THE CANONICAL ONE. The `- type:` line is parsed by the
|
|
20
|
+
* repository's own metadata reader, so a value this command accepts is a
|
|
21
|
+
* value the rest of the pipeline accepts. A type line this command does not
|
|
22
|
+
* understand is left unresolved, and its slice contributes no retro-attributed
|
|
23
|
+
* row — reported as a warning, never as a silent omission.
|
|
24
|
+
*/
|
|
25
|
+
import type { Command } from 'commander';
|
|
26
|
+
import { type RequestTypeReading } from '../../services/observability/hotspot-shared.js';
|
|
27
|
+
import type { ObservabilityEvent } from '../../services/observability/observability-service.js';
|
|
28
|
+
import { type ProgramIO } from '../cli-helpers.js';
|
|
29
|
+
import { type ObservabilityQueryOptions } from './observability-commands-queries.js';
|
|
30
|
+
/**
|
|
31
|
+
* The request types of the slices in the scope, keyed by slice rid.
|
|
32
|
+
*
|
|
33
|
+
* The retro-attribution re-derives a transition's prerequisite list from the
|
|
34
|
+
* request type, and the type lives in the request artifact rather than in the
|
|
35
|
+
* event stream — so a caller that wants the HISTORICAL rows has to resolve
|
|
36
|
+
* the types itself. Without them the ranking holds only the forward events,
|
|
37
|
+
* and on a history that predates the forward emitter it holds NOTHING, which
|
|
38
|
+
* would read as "no hotspot" rather than as "no history".
|
|
39
|
+
*
|
|
40
|
+
* ONE IMPLEMENTATION, TWO CALLERS. The `hotspots` command and the `report`
|
|
41
|
+
* command both need the types, and a second copy of the lookup is a copy that
|
|
42
|
+
* drifts — so both go through this function.
|
|
43
|
+
*/
|
|
44
|
+
export declare function hotspotRequestTypes(projectRoot: string, events: readonly ObservabilityEvent[]): {
|
|
45
|
+
readonly requestTypes: Map<string, RequestTypeReading>;
|
|
46
|
+
readonly unreadable: number;
|
|
47
|
+
readonly defaulted: number;
|
|
48
|
+
};
|
|
49
|
+
/**
|
|
50
|
+
* `peaks observability hotspots` — print the hotspot ranking.
|
|
51
|
+
*/
|
|
52
|
+
export declare function runHotspots(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
53
|
+
/** Register `peaks observability hotspots` under the observability command. */
|
|
54
|
+
export declare function registerHotspotsCommand(observability: Command, io: ProgramIO): void;
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/cli/commands/observability-commands-hotspots.ts`
|
|
3
|
+
*
|
|
4
|
+
* `peaks observability hotspots` — which artifact does a skill keep failing
|
|
5
|
+
* to deliver, and who owns it.
|
|
6
|
+
*
|
|
7
|
+
* WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
|
|
8
|
+
* That file is at its file-size cap and a later task needs room in it too,
|
|
9
|
+
* so each subcommand's registration lives in its own module and the parent
|
|
10
|
+
* gains one import and one call. The precedent is the sibling split of
|
|
11
|
+
* `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
|
|
12
|
+
*
|
|
13
|
+
* WHY THE REQUEST TYPES ARE RESOLVED HERE. The retro-attribution re-derives
|
|
14
|
+
* a transition's prerequisite list, and the table is indexed by request type —
|
|
15
|
+
* a fact that lives in the request artifact, not in the event stream. The
|
|
16
|
+
* events carry the slice; the request artifact carries the type. So this
|
|
17
|
+
* layer reads the request artifacts and hands the types to the ranking.
|
|
18
|
+
*
|
|
19
|
+
* WHY THE READER IS THE CANONICAL ONE. The `- type:` line is parsed by the
|
|
20
|
+
* repository's own metadata reader, so a value this command accepts is a
|
|
21
|
+
* value the rest of the pipeline accepts. A type line this command does not
|
|
22
|
+
* understand is left unresolved, and its slice contributes no retro-attributed
|
|
23
|
+
* row — reported as a warning, never as a silent omission.
|
|
24
|
+
*/
|
|
25
|
+
import { readFileSync, readdirSync } from 'node:fs';
|
|
26
|
+
import { join } from 'node:path';
|
|
27
|
+
import { fail, ok } from 'peaks-loop-shared/result';
|
|
28
|
+
import { isRequestType } from '../../services/artifacts/artifact-prerequisites.js';
|
|
29
|
+
import { extractMetadata } from '../../services/artifacts/request-artifact-metadata.js';
|
|
30
|
+
import { guardRuntimeSegment, runtimeRoot } from '../../shared/runtime-root.js';
|
|
31
|
+
import { slugifyDescription } from '../../shared/incrementing-number.js';
|
|
32
|
+
import { aggregateHotspots } from '../../services/observability/hotspots.js';
|
|
33
|
+
import { summarizeAttribution } from '../../services/observability/hotspot-attribution-summary.js';
|
|
34
|
+
import { groupHotspotsByMeaning } from '../../services/observability/hotspot-shared.js';
|
|
35
|
+
import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
|
|
36
|
+
import { readScopedEvents, resolveProjectRoot, scopeOf, scopeWarnings } from './observability-commands-queries.js';
|
|
37
|
+
/** The request artifact roles a request type can be read from. */
|
|
38
|
+
const REQUEST_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
|
|
39
|
+
/**
|
|
40
|
+
* The request type of every request artifact under the project, AND where each
|
|
41
|
+
* type came from.
|
|
42
|
+
*
|
|
43
|
+
* The map is keyed by the request's SLUG — the same form the artifact's
|
|
44
|
+
* filename carries — because that is the only spelling shared by the file
|
|
45
|
+
* on disk and the request id in the event stream.
|
|
46
|
+
*
|
|
47
|
+
* WHY THE SOURCE RIDES ALONG WITH THE TYPE. An artifact that declares no
|
|
48
|
+
* usable `- type:` line still has an EFFECTIVE type — the system's default —
|
|
49
|
+
* and that is the type the prerequisite table was indexed by when the
|
|
50
|
+
* transition ran, so the attribution must use it. But the effective type and
|
|
51
|
+
* the fact that NOBODY WROTE IT DOWN are two different facts, and a reader
|
|
52
|
+
* asking "how many of these attributions rested on a type nobody wrote
|
|
53
|
+
* down?" cannot answer it if the reader throws the second fact away.
|
|
54
|
+
*
|
|
55
|
+
* THE TWO BUCKETS ARE NOT THE SAME BUCKET. `unreadable` counts artifacts
|
|
56
|
+
* that could not be READ — their type is unknown, so their slice contributes
|
|
57
|
+
* no retro-attributed row at all. `defaulted` counts artifacts that read
|
|
58
|
+
* fine but carry no usable type line: their slice DOES contribute a row,
|
|
59
|
+
* attributed against the default. Conflating them would report a type nobody
|
|
60
|
+
* wrote down as a type nobody could supply.
|
|
61
|
+
*
|
|
62
|
+
* WHY A DECLARED READING WINS OVER A DEFAULTED ONE FOR THE SAME SLUG. A
|
|
63
|
+
* request's artifact is written once per role, and one role's copy may carry
|
|
64
|
+
* a type line while another's does not. The declared line is the stronger
|
|
65
|
+
* fact — it is what a human wrote — so it is the one that names the type.
|
|
66
|
+
*/
|
|
67
|
+
function readRequestTypes(projectRoot) {
|
|
68
|
+
const bySlug = new Map();
|
|
69
|
+
const counts = { unreadable: 0, defaulted: 0 };
|
|
70
|
+
const runtime = runtimeRoot(projectRoot);
|
|
71
|
+
let sessions;
|
|
72
|
+
try {
|
|
73
|
+
sessions = readdirSync(runtime.dir(), { withFileTypes: true })
|
|
74
|
+
.filter((entry) => entry.isDirectory())
|
|
75
|
+
.map((entry) => entry.name);
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
return { bySlug, unreadable: counts.unreadable, defaulted: counts.defaulted };
|
|
79
|
+
}
|
|
80
|
+
for (const session of sessions) {
|
|
81
|
+
for (const role of REQUEST_ROLES) {
|
|
82
|
+
const dir = join(runtime.join(guardRuntimeSegment(session, 'session id'), guardRuntimeSegment(role, 'role'), guardRuntimeSegment('requests', 'leaf')));
|
|
83
|
+
let files;
|
|
84
|
+
try {
|
|
85
|
+
files = readdirSync(dir).filter((name) => name.endsWith('.md'));
|
|
86
|
+
}
|
|
87
|
+
catch {
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
for (const file of files) {
|
|
91
|
+
readOneRequestArtifact(dir, file, bySlug, counts);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
return { bySlug, unreadable: counts.unreadable, defaulted: counts.defaulted };
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* Read ONE request artifact and fold it into the slug map.
|
|
99
|
+
*
|
|
100
|
+
* WHY IT IS ITS OWN FUNCTION. The reader walks every artifact of every
|
|
101
|
+
* session and role, and the three facts it collects — the reading, the
|
|
102
|
+
* unreadable count, the no-type-line count — are counted as it goes. Folding
|
|
103
|
+
* one artifact's handling into its own function keeps each step readable and
|
|
104
|
+
* keeps the reader's size under the cap.
|
|
105
|
+
*
|
|
106
|
+
* THE COUNTING RULES. An artifact that cannot be READ is `unreadable` — its
|
|
107
|
+
* slice's type is unknown, so nothing can be attributed to it. An artifact
|
|
108
|
+
* that reads but whose type line is unusable is `defaulted` — its slice still
|
|
109
|
+
* gets the default type, and the attribution is real but its provenance is
|
|
110
|
+
* not. The two are different facts and they do not share a bucket.
|
|
111
|
+
*/
|
|
112
|
+
function readOneRequestArtifact(dir, file, bySlug, counts) {
|
|
113
|
+
let markdown;
|
|
114
|
+
try {
|
|
115
|
+
markdown = readFileSync(join(dir, file), 'utf8');
|
|
116
|
+
}
|
|
117
|
+
catch {
|
|
118
|
+
counts.unreadable += 1;
|
|
119
|
+
return;
|
|
120
|
+
}
|
|
121
|
+
const { requestType, requestTypeSource } = extractMetadata(markdown);
|
|
122
|
+
if (!isRequestType(requestType)) {
|
|
123
|
+
counts.unreadable += 1;
|
|
124
|
+
return;
|
|
125
|
+
}
|
|
126
|
+
if (requestTypeSource === 'default')
|
|
127
|
+
counts.defaulted += 1;
|
|
128
|
+
const slug = file.replace(/^\d{3}-/, '').replace(/\.md$/, '');
|
|
129
|
+
const existing = bySlug.get(slug);
|
|
130
|
+
if (existing === undefined || existing.source === 'default') {
|
|
131
|
+
bySlug.set(slug, { requestType, source: requestTypeSource });
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* The request types of the slices in the scope, keyed by slice rid.
|
|
136
|
+
*
|
|
137
|
+
* The retro-attribution re-derives a transition's prerequisite list from the
|
|
138
|
+
* request type, and the type lives in the request artifact rather than in the
|
|
139
|
+
* event stream — so a caller that wants the HISTORICAL rows has to resolve
|
|
140
|
+
* the types itself. Without them the ranking holds only the forward events,
|
|
141
|
+
* and on a history that predates the forward emitter it holds NOTHING, which
|
|
142
|
+
* would read as "no hotspot" rather than as "no history".
|
|
143
|
+
*
|
|
144
|
+
* ONE IMPLEMENTATION, TWO CALLERS. The `hotspots` command and the `report`
|
|
145
|
+
* command both need the types, and a second copy of the lookup is a copy that
|
|
146
|
+
* drifts — so both go through this function.
|
|
147
|
+
*/
|
|
148
|
+
export function hotspotRequestTypes(projectRoot, events) {
|
|
149
|
+
const { bySlug, unreadable, defaulted } = readRequestTypes(projectRoot);
|
|
150
|
+
const requestTypes = new Map();
|
|
151
|
+
for (const event of events) {
|
|
152
|
+
const rid = event.sliceRid;
|
|
153
|
+
if (rid === undefined)
|
|
154
|
+
continue;
|
|
155
|
+
const reading = bySlug.get(slugifyDescription(rid));
|
|
156
|
+
if (reading !== undefined && !requestTypes.has(rid))
|
|
157
|
+
requestTypes.set(rid, reading);
|
|
158
|
+
}
|
|
159
|
+
return { requestTypes, unreadable, defaulted };
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* What the reader found while it read the request artifacts, said plainly.
|
|
163
|
+
*
|
|
164
|
+
* WHY THE TWO FACTS ARE TWO WARNINGS. An artifact that could not be READ
|
|
165
|
+
* leaves its slice with no type at all, so nothing is attributed to it — that
|
|
166
|
+
* is a GAP. An artifact that read fine but carried no usable type line leaves
|
|
167
|
+
* its slice with the DEFAULT type, so an attribution IS produced, and only its
|
|
168
|
+
* PROVENANCE is weak. One warning per fact, so a reader can tell which
|
|
169
|
+
* happened without reading the code.
|
|
170
|
+
*/
|
|
171
|
+
function requestTypeWarnings(unreadable, defaulted) {
|
|
172
|
+
const warnings = [];
|
|
173
|
+
if (unreadable > 0) {
|
|
174
|
+
warnings.push(`${unreadable} request artifact(s) could not be read, so the slices they belong to have ` +
|
|
175
|
+
'no known request type and contribute no retro-attributed row.');
|
|
176
|
+
}
|
|
177
|
+
if (defaulted > 0) {
|
|
178
|
+
warnings.push(`${defaulted} request artifact(s) carry no usable \`- type:\` line, so their slices are ` +
|
|
179
|
+
'attributed against the DEFAULT request type — a type nobody wrote down. The ' +
|
|
180
|
+
'attribution is real; its provenance is not.');
|
|
181
|
+
}
|
|
182
|
+
return warnings;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* `peaks observability hotspots` — print the hotspot ranking.
|
|
186
|
+
*/
|
|
187
|
+
export function runHotspots(io, options) {
|
|
188
|
+
const projectRoot = resolveProjectRoot(options.project);
|
|
189
|
+
try {
|
|
190
|
+
const { sessionId, events } = readScopedEvents(projectRoot, options);
|
|
191
|
+
const { requestTypes, unreadable, defaulted } = hotspotRequestTypes(projectRoot, events);
|
|
192
|
+
const hotspots = aggregateHotspots(events, requestTypes);
|
|
193
|
+
const attribution = summarizeAttribution(events, requestTypes, {
|
|
194
|
+
unreadable,
|
|
195
|
+
withoutTypeLine: defaulted
|
|
196
|
+
});
|
|
197
|
+
const warnings = [
|
|
198
|
+
...scopeWarnings(projectRoot, sessionId, events.length),
|
|
199
|
+
...requestTypeWarnings(unreadable, defaulted)
|
|
200
|
+
];
|
|
201
|
+
printResult(io, ok('observability.hotspots', {
|
|
202
|
+
scope: scopeOf(sessionId),
|
|
203
|
+
hotspots: groupHotspotsByMeaning(hotspots),
|
|
204
|
+
attribution
|
|
205
|
+
}, warnings), options.json);
|
|
206
|
+
}
|
|
207
|
+
catch (error) {
|
|
208
|
+
printResult(io, fail('observability.hotspots', 'OBSERVABILITY_HOTSPOTS_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
|
|
209
|
+
process.exitCode = 1;
|
|
210
|
+
}
|
|
211
|
+
}
|
|
212
|
+
/** Register `peaks observability hotspots` under the observability command. */
|
|
213
|
+
export function registerHotspotsCommand(observability, io) {
|
|
214
|
+
addJsonOption(observability
|
|
215
|
+
.command('hotspots')
|
|
216
|
+
.description('Hotspot ranking: which artifact a skill keeps failing to deliver, and who owns it. The rows are split by what their count COUNTS, so the group a row is in says what its number means: `observedOmissions` are MEASURED (the artifact was seen missing that many times) and `candidateMentions` are CANDIDATES recovered from a historical count (one real failure counts toward EVERY candidate it could not narrow, so those numbers are an upper bound, NOT a count of failures). Each row also carries its owner, artifact, mode and confidence; the confidence values are unchanged.')
|
|
217
|
+
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
218
|
+
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
219
|
+
.option('--all-sessions', 'measure the whole recorded history of the project instead of the canonical session binding')).action((options) => {
|
|
220
|
+
runHotspots(io, options);
|
|
221
|
+
});
|
|
222
|
+
}
|