peaks-loop 4.1.22 → 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 +2 -2
- package/CHANGELOG.md +82 -0
- 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/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
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,87 @@
|
|
|
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
|
+
|
|
3
85
|
## 4.1.22 — 2026-10-25(把"只测了两个子命令"的漏测补上,把"不是缺陷"的两条说准)
|
|
4
86
|
|
|
5
87
|
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何运行时语义、
|
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/cli/commands/observability-commands-near-miss.ts`
|
|
3
|
+
*
|
|
4
|
+
* `peaks observability near-miss` — the headline number of the whole
|
|
5
|
+
* programme: of the slices that passed, how many passed anyway after a gate
|
|
6
|
+
* that was live never got evaluated?
|
|
7
|
+
*
|
|
8
|
+
* WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
|
|
9
|
+
* That file is at its file-size cap and a later task needs room in it too,
|
|
10
|
+
* so each subcommand's registration lives in its own module and the parent
|
|
11
|
+
* gains one import and one call. The precedent is the sibling split of
|
|
12
|
+
* `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
|
|
13
|
+
*
|
|
14
|
+
* WHY THE SCOPE BEHAVES LIKE THE OTHER QUERIES. The scope resolution, the
|
|
15
|
+
* `--all-sessions` escape and the empty-scope warning are the shared ones in
|
|
16
|
+
* `observability-commands-queries.ts`, so this command measures the same
|
|
17
|
+
* population its siblings report and says so the same way when it is empty.
|
|
18
|
+
*/
|
|
19
|
+
import type { Command } from 'commander';
|
|
20
|
+
import { type ProgramIO } from '../cli-helpers.js';
|
|
21
|
+
import { type ObservabilityQueryOptions } from './observability-commands-queries.js';
|
|
22
|
+
/**
|
|
23
|
+
* `peaks observability near-miss` — print the near-miss rate and the list of
|
|
24
|
+
* slices it came from.
|
|
25
|
+
*/
|
|
26
|
+
export declare function runNearMiss(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
27
|
+
/** Register `peaks observability near-miss` under the observability command. */
|
|
28
|
+
export declare function registerNearMissCommand(observability: Command, io: ProgramIO): void;
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/cli/commands/observability-commands-near-miss.ts`
|
|
3
|
+
*
|
|
4
|
+
* `peaks observability near-miss` — the headline number of the whole
|
|
5
|
+
* programme: of the slices that passed, how many passed anyway after a gate
|
|
6
|
+
* that was live never got evaluated?
|
|
7
|
+
*
|
|
8
|
+
* WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
|
|
9
|
+
* That file is at its file-size cap and a later task needs room in it too,
|
|
10
|
+
* so each subcommand's registration lives in its own module and the parent
|
|
11
|
+
* gains one import and one call. The precedent is the sibling split of
|
|
12
|
+
* `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
|
|
13
|
+
*
|
|
14
|
+
* WHY THE SCOPE BEHAVES LIKE THE OTHER QUERIES. The scope resolution, the
|
|
15
|
+
* `--all-sessions` escape and the empty-scope warning are the shared ones in
|
|
16
|
+
* `observability-commands-queries.ts`, so this command measures the same
|
|
17
|
+
* population its siblings report and says so the same way when it is empty.
|
|
18
|
+
*/
|
|
19
|
+
import { fail, ok } from 'peaks-loop-shared/result';
|
|
20
|
+
import { computeNearMiss } from '../../services/observability/near-miss.js';
|
|
21
|
+
import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
|
|
22
|
+
import { hotspotRequestTypes } from './observability-commands-hotspots.js';
|
|
23
|
+
import { readScopedEvents, resolveProjectRoot, scopeOf, scopeWarnings } from './observability-commands-queries.js';
|
|
24
|
+
/**
|
|
25
|
+
* The warning that says a reason class had no events to observe.
|
|
26
|
+
*
|
|
27
|
+
* A class with no events cannot produce a finding, so its share of the rate
|
|
28
|
+
* is an ABSENCE OF DATA. Saying nothing would let a reader take the rate for
|
|
29
|
+
* "no near-misses" when the truth is "this class was never looked at" — the
|
|
30
|
+
* exact misreading the metric exists to prevent.
|
|
31
|
+
*/
|
|
32
|
+
function coverageWarnings(coverage) {
|
|
33
|
+
return coverage
|
|
34
|
+
.filter((item) => !item.observable)
|
|
35
|
+
.map((item) => `The \`${item.reason}\` class had NO events to observe in this scope ` +
|
|
36
|
+
`(${item.scopeEventCount} event(s)), so its share of the near-miss rate is an ` +
|
|
37
|
+
'absence of data, not a result — the rate does not measure that class.');
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* The warning that says the denominator differs from the status summary's.
|
|
41
|
+
*
|
|
42
|
+
* "Passed" has two definitions in this repository and they do not count the
|
|
43
|
+
* same slices. A reader who sees one number and assumes it is the other's
|
|
44
|
+
* would be wrong, so the difference is stated rather than smoothed over.
|
|
45
|
+
*/
|
|
46
|
+
function denominatorWarnings(denominator) {
|
|
47
|
+
if (denominator.difference === null)
|
|
48
|
+
return [];
|
|
49
|
+
return [denominator.difference.note];
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* The warning that says a slice could not be measured at all.
|
|
53
|
+
*
|
|
54
|
+
* A slice whose `verdict-issued` attempt records a prereq verdict this build
|
|
55
|
+
* cannot read is in neither the numerator nor the denominator, so a reader who
|
|
56
|
+
* adds up the slices finds one missing. Saying nothing would let them infer
|
|
57
|
+
* it was never there.
|
|
58
|
+
*/
|
|
59
|
+
function unmeasuredWarnings(unmeasured) {
|
|
60
|
+
if (unmeasured.length === 0)
|
|
61
|
+
return [];
|
|
62
|
+
return [
|
|
63
|
+
`${unmeasured.length} slice(s) recorded a \`verdict-issued\` attempt whose prereq verdict this ` +
|
|
64
|
+
'build cannot read, so whether they passed is unknown — they are in neither the numerator ' +
|
|
65
|
+
`nor the denominator: ${unmeasured.map((item) => `\`${item.sliceRid}\``).join(', ')}`
|
|
66
|
+
];
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* `peaks observability near-miss` — print the near-miss rate and the list of
|
|
70
|
+
* slices it came from.
|
|
71
|
+
*/
|
|
72
|
+
export function runNearMiss(io, options) {
|
|
73
|
+
const projectRoot = resolveProjectRoot(options.project);
|
|
74
|
+
try {
|
|
75
|
+
const { sessionId, events } = readScopedEvents(projectRoot, options);
|
|
76
|
+
// The request types let the denominator NAME the cause of the gap between
|
|
77
|
+
// the two "passed" definitions: the slices that reached a verdict with no
|
|
78
|
+
// recorded prereq verdict are the ones whose type has no
|
|
79
|
+
// `qa:verdict-issued` prerequisite row at all.
|
|
80
|
+
const { requestTypes } = hotspotRequestTypes(projectRoot, events);
|
|
81
|
+
const report = computeNearMiss(events, requestTypes);
|
|
82
|
+
const warnings = [
|
|
83
|
+
...scopeWarnings(projectRoot, sessionId, events.length),
|
|
84
|
+
...coverageWarnings(report.coverage),
|
|
85
|
+
...denominatorWarnings(report.denominator),
|
|
86
|
+
...unmeasuredWarnings(report.unmeasured)
|
|
87
|
+
];
|
|
88
|
+
printResult(io, ok('observability.near-miss', { scope: scopeOf(sessionId), ...report }, warnings), options.json);
|
|
89
|
+
}
|
|
90
|
+
catch (error) {
|
|
91
|
+
printResult(io, fail('observability.near-miss', 'OBSERVABILITY_NEAR_MISS_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
|
|
92
|
+
process.exitCode = 1;
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
/** Register `peaks observability near-miss` under the observability command. */
|
|
96
|
+
export function registerNearMissCommand(observability, io) {
|
|
97
|
+
addJsonOption(observability
|
|
98
|
+
.command('near-miss')
|
|
99
|
+
.description('Near-miss rate: of the slices that were DECLARED PASSING (a `verdict-issued` attempt whose prereq check succeeded), how many passed anyway after a required check was still unsatisfied at that moment, or after a live gate never got evaluated? The `denominator` field states the definition and size of the population the rate divides by, and reconciles it with the status summary\'s success count — the two "passed" definitions do not count the same slices, and the difference is reported rather than smoothed over. The `coverage` field says, per reason class, whether that class had any events to observe: a class with none was not measured, so its share of the rate is an absence of data rather than a result.')
|
|
100
|
+
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
101
|
+
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
102
|
+
.option('--all-sessions', 'measure the whole recorded history of the project instead of the canonical session binding')).action((options) => {
|
|
103
|
+
runNearMiss(io, options);
|
|
104
|
+
});
|
|
105
|
+
}
|
|
@@ -15,28 +15,71 @@
|
|
|
15
15
|
* LATER ADDITION — `peaks observability repair-cycles` also grew an
|
|
16
16
|
* `--all-sessions` scope, so the whole recorded history of a project can be
|
|
17
17
|
* measured from the command itself.
|
|
18
|
+
*
|
|
19
|
+
* TASK 4 — the same `--all-sessions` scope now reaches `status` / `slices` /
|
|
20
|
+
* `fanout` / `report`, and every scoped query says so when its scope holds no
|
|
21
|
+
* events while OTHER sessions hold some.
|
|
18
22
|
*/
|
|
23
|
+
import { readAllSessionEvents } from '../../services/observability/aggregation.js';
|
|
19
24
|
import { type ProgramIO } from '../cli-helpers.js';
|
|
20
25
|
export declare function resolveProjectRoot(optionProject: string | undefined): string;
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
session?: string;
|
|
30
|
-
json?: boolean;
|
|
31
|
-
}): void;
|
|
32
|
-
export declare function runFanout(io: ProgramIO, options: {
|
|
33
|
-
project?: string;
|
|
34
|
-
session?: string;
|
|
35
|
-
json?: boolean;
|
|
36
|
-
}): void;
|
|
37
|
-
export declare function runRepairCycles(io: ProgramIO, options: {
|
|
26
|
+
/**
|
|
27
|
+
* The options every read-only observability query accepts.
|
|
28
|
+
*
|
|
29
|
+
* `allSessions` widens the scope from the canonical session binding to the
|
|
30
|
+
* WHOLE recorded history of the project — the same flag, and the same
|
|
31
|
+
* meaning, that `repair-cycles` already carries.
|
|
32
|
+
*/
|
|
33
|
+
export type ObservabilityQueryOptions = {
|
|
38
34
|
project?: string;
|
|
39
35
|
session?: string;
|
|
40
36
|
json?: boolean;
|
|
41
37
|
allSessions?: boolean;
|
|
42
|
-
}
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* The session a query reads, or `undefined` for EVERY session.
|
|
41
|
+
*
|
|
42
|
+
* `allSessions` short-circuits the resolution: the whole recorded history is
|
|
43
|
+
* read instead of the canonical session binding, and an explicit `--session`
|
|
44
|
+
* does not narrow it back. That is the precedence `repair-cycles
|
|
45
|
+
* --all-sessions` already has.
|
|
46
|
+
*/
|
|
47
|
+
export declare function resolveSessionId(optionSession: string | undefined, projectRoot: string, allSessions: boolean): string | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* The warnings a scoped query carries.
|
|
50
|
+
*
|
|
51
|
+
* A scoped query that reads zero events reads exactly like a project that
|
|
52
|
+
* recorded nothing, and the reader concludes the second — the events that ARE
|
|
53
|
+
* there stay invisible. So when the scope is empty while OTHER sessions hold
|
|
54
|
+
* events, the warning says how many sessions hold them, how many events in
|
|
55
|
+
* total, and names the flag that reaches them.
|
|
56
|
+
*
|
|
57
|
+
* Empty otherwise: either the scope holds events, or the scope already
|
|
58
|
+
* covers every session.
|
|
59
|
+
*/
|
|
60
|
+
export declare function scopeWarnings(projectRoot: string, scopedSessionId: string | undefined, scopedEventCount: number): string[];
|
|
61
|
+
/** What a scoped query reads: the session it was scoped to, and its events. */
|
|
62
|
+
export type ScopedRead = {
|
|
63
|
+
readonly sessionId: string | undefined;
|
|
64
|
+
readonly events: ReturnType<typeof readAllSessionEvents>;
|
|
65
|
+
};
|
|
66
|
+
/**
|
|
67
|
+
* The events a scoped query answers for: the one session the scope names, or
|
|
68
|
+
* every session the project recorded.
|
|
69
|
+
*/
|
|
70
|
+
export declare function readScopedEvents(projectRoot: string, options: ObservabilityQueryOptions): ScopedRead;
|
|
71
|
+
/**
|
|
72
|
+
* The scope a query answered for: one session, or every session.
|
|
73
|
+
*
|
|
74
|
+
* ONE spelling of that shape, exported because the report command answers
|
|
75
|
+
* with it too: a scope written two ways is a scope that can drift.
|
|
76
|
+
*/
|
|
77
|
+
export declare function scopeOf(sessionId: string | undefined): {
|
|
78
|
+
sessionId: string;
|
|
79
|
+
} | {
|
|
80
|
+
allSessions: true;
|
|
81
|
+
};
|
|
82
|
+
export declare function runStatus(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
83
|
+
export declare function runSlices(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
84
|
+
export declare function runFanout(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
85
|
+
export declare function runRepairCycles(io: ProgramIO, options: ObservabilityQueryOptions): void;
|