peaks-loop 4.1.20 → 4.1.22
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 +198 -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-baseline.d.ts +26 -0
- package/dist/cli/commands/observability-commands-baseline.js +74 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
- package/dist/cli/commands/observability-commands-queries.js +8 -1
- package/dist/cli/commands/observability-commands.d.ts +7 -1
- package/dist/cli/commands/observability-commands.js +19 -3
- package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
- package/dist/services/artifacts/repair-cycle-service.js +23 -0
- 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-helpers.d.ts +12 -8
- package/dist/services/observability/aggregation-helpers.js +12 -25
- package/dist/services/observability/aggregation-types.d.ts +40 -0
- package/dist/services/observability/aggregation.d.ts +2 -1
- package/dist/services/observability/aggregation.js +16 -25
- package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
- package/dist/services/observability/repair-cycle-metric.js +223 -0
- package/dist/services/observability/report-formatter.d.ts +1 -1
- package/dist/services/observability/report-formatter.js +16 -4
- package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
- package/dist/services/observability/results-baseline-artifact.js +80 -0
- package/dist/services/observability/results-baseline-rows.d.ts +33 -0
- package/dist/services/observability/results-baseline-rows.js +127 -0
- package/dist/services/observability/results-baseline.d.ts +115 -0
- package/dist/services/observability/results-baseline.js +101 -0
- package/package.json +7 -5
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/** The two knobs of prettier's JSON layout a render can depend on. */
|
|
2
|
+
export interface JsonLayoutOptions {
|
|
3
|
+
/** prettier's `printWidth` — the column budget one printed line may use. */
|
|
4
|
+
readonly printWidth: number;
|
|
5
|
+
/** prettier's `tabWidth` — how many spaces one indentation level is. */
|
|
6
|
+
readonly tabWidth: number;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* prettier's own defaults, used when the repository's config says nothing about a
|
|
10
|
+
* knob. They are prettier's, not this repository's: the config file is the one
|
|
11
|
+
* source of truth for the numbers, and a second copy of them here would be a
|
|
12
|
+
* second decision.
|
|
13
|
+
*/
|
|
14
|
+
export declare const DEFAULT_JSON_LAYOUT: JsonLayoutOptions;
|
|
15
|
+
/**
|
|
16
|
+
* Render a JSON value in the layout prettier produces for JSON, newline-terminated.
|
|
17
|
+
*
|
|
18
|
+
* The output is a prettier FIXED POINT: formatting it again returns it unchanged.
|
|
19
|
+
*/
|
|
20
|
+
export declare function renderJsonDocument(value: unknown, options?: JsonLayoutOptions): string;
|
|
@@ -0,0 +1,195 @@
|
|
|
1
|
+
// src/services/distribution/json-layout.ts
|
|
2
|
+
//
|
|
3
|
+
// WHY THIS FILE EXISTS. `.claude-plugin/marketplace.json` is a GENERATED artifact
|
|
4
|
+
// and it SHIPS (the root `package.json#files` allowlist names `.claude-plugin/**`),
|
|
5
|
+
// so its bytes are a published surface. The renderer used to emit it with
|
|
6
|
+
// `JSON.stringify(manifest, null, 2)`, which expands EVERY array regardless of
|
|
7
|
+
// width — so the artifact was not prettier-clean, and `npm run format:check` could
|
|
8
|
+
// not see it: that script covers `src|tests|packages|scripts` × `ts,mts,mjs,js` and
|
|
9
|
+
// no `.json` at all. Nothing asserted the property until a guard did.
|
|
10
|
+
//
|
|
11
|
+
// THE RULE IS PRETTIER'S, AND IT IS REPLICATED HERE WITHOUT PRETTIER. `prettier`
|
|
12
|
+
// is a devDependency. The root `package.json#files` allowlist also names
|
|
13
|
+
// `dist/**/*.js`, so `dist/services/distribution/plugin-manifest.js` — and this
|
|
14
|
+
// module beside it — SHIP to consumers. A static `import 'prettier'` from any
|
|
15
|
+
// module under `src/**` would put an undeclared dependency into every consumer
|
|
16
|
+
// install and fail with `ERR_MODULE_NOT_FOUND` — the same defect class as the
|
|
17
|
+
// 4.1.18→4.1.20 packaging break. A lazy `await import('prettier')` would not fail
|
|
18
|
+
// at import time, but it would still make the SHIPPED renderer's output depend on a
|
|
19
|
+
// package the published manifest does not declare. So the shape is computed here,
|
|
20
|
+
// with ZERO dependencies, and the shape does not drift when prettier is upgraded.
|
|
21
|
+
//
|
|
22
|
+
// THE TWO RULES, AS PRETTIER APPLIES THEM TO JSON.
|
|
23
|
+
//
|
|
24
|
+
// 1. OBJECTS. prettier keeps an object expanded when the source has a newline
|
|
25
|
+
// between `{` and its first key, and collapses it otherwise. This renderer
|
|
26
|
+
// always emits the newline, so every object is expanded — and prettier, reading
|
|
27
|
+
// that newline, keeps it expanded. The render is therefore a FIXED POINT of
|
|
28
|
+
// prettier, which is the property the guard asserts.
|
|
29
|
+
//
|
|
30
|
+
// 2. ARRAYS. prettier prints an array on ONE line when it fits the print width,
|
|
31
|
+
// and breaks it one element per line when it does not. On top of that it has
|
|
32
|
+
// one forced-break rule: an array with more than one element where EVERY
|
|
33
|
+
// element is an object or an array, all of the same kind, and each holding
|
|
34
|
+
// more than one member, breaks even when it would fit.
|
|
35
|
+
//
|
|
36
|
+
// The width is measured the way prettier measures it: the printed line, from its
|
|
37
|
+
// indentation through the value and the separator that follows it, must fit inside
|
|
38
|
+
// `printWidth`. A value therefore knows the column it starts at, the text already
|
|
39
|
+
// on its line, and the text that follows it before the next break.
|
|
40
|
+
//
|
|
41
|
+
// MEASURED, NOT ASSUMED. This rule was differential-tested against the installed
|
|
42
|
+
// prettier over 3000 generated manifests: the render equalled
|
|
43
|
+
// `prettier.format(JSON.stringify(value, null, 2))` in 3000 of 3000 cases, and
|
|
44
|
+
// `prettier.format(render(value)) === render(value)` in 3000 of 3000. The guard
|
|
45
|
+
// that keeps the property is
|
|
46
|
+
// `tests/unit/services/distribution/plugin-manifest-prettier-clean.test.ts`.
|
|
47
|
+
/**
|
|
48
|
+
* prettier's own defaults, used when the repository's config says nothing about a
|
|
49
|
+
* knob. They are prettier's, not this repository's: the config file is the one
|
|
50
|
+
* source of truth for the numbers, and a second copy of them here would be a
|
|
51
|
+
* second decision.
|
|
52
|
+
*/
|
|
53
|
+
export const DEFAULT_JSON_LAYOUT = { printWidth: 80, tabWidth: 2 };
|
|
54
|
+
function isPrimitive(value) {
|
|
55
|
+
return value === null || typeof value !== 'object';
|
|
56
|
+
}
|
|
57
|
+
function isJsonArray(value) {
|
|
58
|
+
return Array.isArray(value);
|
|
59
|
+
}
|
|
60
|
+
function isJsonObject(value) {
|
|
61
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
62
|
+
}
|
|
63
|
+
/** One JSON literal. `undefined` is not a JSON value, so it reads as `null`. */
|
|
64
|
+
function literal(value) {
|
|
65
|
+
return JSON.stringify(value) ?? 'null';
|
|
66
|
+
}
|
|
67
|
+
/**
|
|
68
|
+
* prettier's forced-break rule for arrays. An array breaks even when it would fit
|
|
69
|
+
* when it holds more than one element, every element is an object or an array, all
|
|
70
|
+
* of them are the same kind, and each one holds more than one member.
|
|
71
|
+
*/
|
|
72
|
+
function forcesBreak(elements) {
|
|
73
|
+
if (elements.length <= 1)
|
|
74
|
+
return false;
|
|
75
|
+
return elements.every((element, index, all) => {
|
|
76
|
+
const next = all[index + 1];
|
|
77
|
+
if (isJsonArray(element)) {
|
|
78
|
+
if (next !== undefined && !isJsonArray(next))
|
|
79
|
+
return false;
|
|
80
|
+
return element.length > 1;
|
|
81
|
+
}
|
|
82
|
+
if (isJsonObject(element)) {
|
|
83
|
+
if (next !== undefined && !isJsonObject(next))
|
|
84
|
+
return false;
|
|
85
|
+
return Object.keys(element).length > 1;
|
|
86
|
+
}
|
|
87
|
+
return false;
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* A non-empty object anywhere below this value forces every enclosing array to
|
|
92
|
+
* break: this renderer always expands an object, and an expanded member breaks the
|
|
93
|
+
* group that holds it.
|
|
94
|
+
*/
|
|
95
|
+
function containsObject(value) {
|
|
96
|
+
if (isPrimitive(value))
|
|
97
|
+
return false;
|
|
98
|
+
if (isJsonArray(value))
|
|
99
|
+
return value.some(containsObject);
|
|
100
|
+
if (isJsonObject(value))
|
|
101
|
+
return Object.keys(value).length > 0;
|
|
102
|
+
return false;
|
|
103
|
+
}
|
|
104
|
+
/** A forced-break array anywhere below this value breaks every enclosing array. */
|
|
105
|
+
function containsForcedBreak(value) {
|
|
106
|
+
if (isPrimitive(value))
|
|
107
|
+
return false;
|
|
108
|
+
if (isJsonArray(value))
|
|
109
|
+
return forcesBreak(value) || value.some(containsForcedBreak);
|
|
110
|
+
return false;
|
|
111
|
+
}
|
|
112
|
+
/** The one-line rendering of a value — the width an enclosing array measures. */
|
|
113
|
+
function flatText(value) {
|
|
114
|
+
if (isPrimitive(value))
|
|
115
|
+
return literal(value);
|
|
116
|
+
if (isJsonArray(value))
|
|
117
|
+
return `[${value.map(flatText).join(', ')}]`;
|
|
118
|
+
if (!isJsonObject(value))
|
|
119
|
+
return 'null';
|
|
120
|
+
const keys = Object.keys(value);
|
|
121
|
+
if (keys.length === 0)
|
|
122
|
+
return '{}';
|
|
123
|
+
const members = keys.map((key) => `${JSON.stringify(key)}: ${flatText(value[key])}`);
|
|
124
|
+
return `{ ${members.join(', ')} }`;
|
|
125
|
+
}
|
|
126
|
+
function renderValue(value, context) {
|
|
127
|
+
if (isPrimitive(value))
|
|
128
|
+
return literal(value);
|
|
129
|
+
if (isJsonArray(value))
|
|
130
|
+
return renderArray(value, context);
|
|
131
|
+
if (isJsonObject(value))
|
|
132
|
+
return renderObject(value, context);
|
|
133
|
+
return literal(value);
|
|
134
|
+
}
|
|
135
|
+
/** One array, either on one line or one element per line. */
|
|
136
|
+
function renderArray(elements, context) {
|
|
137
|
+
if (elements.length === 0)
|
|
138
|
+
return '[]';
|
|
139
|
+
const flat = `[${elements.map(flatText).join(', ')}]`;
|
|
140
|
+
const fits = context.indent + context.prefixWidth + flat.length + context.suffixWidth <=
|
|
141
|
+
context.options.printWidth;
|
|
142
|
+
const breakable = forcesBreak(elements) || containsObject(elements) || containsForcedBreak(elements);
|
|
143
|
+
if (fits && !breakable)
|
|
144
|
+
return flat;
|
|
145
|
+
const inner = context.indent + context.options.tabWidth;
|
|
146
|
+
const pad = ' '.repeat(inner);
|
|
147
|
+
const body = elements
|
|
148
|
+
.map((element, index) => {
|
|
149
|
+
const child = {
|
|
150
|
+
options: context.options,
|
|
151
|
+
indent: inner,
|
|
152
|
+
prefixWidth: 0,
|
|
153
|
+
suffixWidth: index === elements.length - 1 ? 0 : 1
|
|
154
|
+
};
|
|
155
|
+
return pad + renderValue(element, child);
|
|
156
|
+
})
|
|
157
|
+
.join(',\n');
|
|
158
|
+
return `[\n${body}\n${' '.repeat(context.indent)}]`;
|
|
159
|
+
}
|
|
160
|
+
/** One object, always expanded — the newline after `{` is what keeps it so. */
|
|
161
|
+
function renderObject(value, context) {
|
|
162
|
+
const keys = Object.keys(value);
|
|
163
|
+
if (keys.length === 0)
|
|
164
|
+
return '{}';
|
|
165
|
+
const inner = context.indent + context.options.tabWidth;
|
|
166
|
+
const pad = ' '.repeat(inner);
|
|
167
|
+
const body = keys
|
|
168
|
+
.map((key, index) => {
|
|
169
|
+
const keyText = JSON.stringify(key);
|
|
170
|
+
const child = {
|
|
171
|
+
options: context.options,
|
|
172
|
+
indent: inner,
|
|
173
|
+
// the `": "` that follows the key
|
|
174
|
+
prefixWidth: keyText.length + 2,
|
|
175
|
+
suffixWidth: index === keys.length - 1 ? 0 : 1
|
|
176
|
+
};
|
|
177
|
+
return `${pad}${keyText}: ${renderValue(value[key], child)}`;
|
|
178
|
+
})
|
|
179
|
+
.join(',\n');
|
|
180
|
+
return `{\n${body}\n${' '.repeat(context.indent)}}`;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Render a JSON value in the layout prettier produces for JSON, newline-terminated.
|
|
184
|
+
*
|
|
185
|
+
* The output is a prettier FIXED POINT: formatting it again returns it unchanged.
|
|
186
|
+
*/
|
|
187
|
+
export function renderJsonDocument(value, options = DEFAULT_JSON_LAYOUT) {
|
|
188
|
+
const text = renderValue(value, {
|
|
189
|
+
options,
|
|
190
|
+
indent: 0,
|
|
191
|
+
prefixWidth: 0,
|
|
192
|
+
suffixWidth: 0
|
|
193
|
+
});
|
|
194
|
+
return `${text}\n`;
|
|
195
|
+
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type SkillMetadata } from '../skills/skill-registry.js';
|
|
2
|
+
import { type JsonLayoutOptions } from './json-layout.js';
|
|
2
3
|
/** Where the generator writes, relative to the package root. */
|
|
3
4
|
export declare const PLUGIN_MANIFEST_RELATIVE_PATH = ".claude-plugin/marketplace.json";
|
|
4
5
|
/**
|
|
@@ -20,6 +21,16 @@ interface PackageManifest {
|
|
|
20
21
|
} | string;
|
|
21
22
|
readonly license?: string;
|
|
22
23
|
readonly keywords?: readonly string[];
|
|
24
|
+
/**
|
|
25
|
+
* The repository's own prettier config — the source of truth for the layout the
|
|
26
|
+
* artifact is rendered in. Read from the SAME package.json the plugin-level
|
|
27
|
+
* fields come from, so the render and the check that guards it cannot disagree
|
|
28
|
+
* about the width.
|
|
29
|
+
*/
|
|
30
|
+
readonly prettier?: {
|
|
31
|
+
readonly printWidth?: number;
|
|
32
|
+
readonly tabWidth?: number;
|
|
33
|
+
};
|
|
23
34
|
}
|
|
24
35
|
/** One plugin entry's skill list item — the shape `peaks skill:visibility` reads. */
|
|
25
36
|
interface PluginSkillEntry {
|
|
@@ -78,8 +89,26 @@ export declare function skillEntriesOf(skills: readonly SkillMetadata[]): readon
|
|
|
78
89
|
* caller that must fail loudly on an unreadable SKILL.md can do so once.
|
|
79
90
|
*/
|
|
80
91
|
export declare function generatePluginManifest(manifest: PackageManifest, skills: readonly SkillMetadata[]): GeneratedPluginManifest;
|
|
81
|
-
/**
|
|
82
|
-
|
|
92
|
+
/**
|
|
93
|
+
* The layout the repository's own prettier config asks for, read from the ROOT
|
|
94
|
+
* package.json. Exported so the guard that checks the artifact resolves the layout
|
|
95
|
+
* the same way the renderer does — two resolutions would be two decisions.
|
|
96
|
+
*/
|
|
97
|
+
export declare function repositoryJsonLayout(): JsonLayoutOptions;
|
|
98
|
+
/**
|
|
99
|
+
* The artifact's bytes, newline-terminated — the same serialization contract as the
|
|
100
|
+
* whitelist, in the layout prettier produces for JSON.
|
|
101
|
+
*
|
|
102
|
+
* `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
|
|
103
|
+
* regardless of width, so the committed artifact was not prettier-clean. The shape
|
|
104
|
+
* is now computed by `json-layout.ts`, which implements prettier's JSON rules with
|
|
105
|
+
* ZERO dependencies — `prettier` is a devDependency, and this module ships to
|
|
106
|
+
* consumers inside `dist/**`, so it must not depend on it.
|
|
107
|
+
*
|
|
108
|
+
* The default layout is the repository's own, read from the root `package.json`;
|
|
109
|
+
* a caller rendering for another root passes the layout it resolved there.
|
|
110
|
+
*/
|
|
111
|
+
export declare function serializePluginManifest(manifest: GeneratedPluginManifest, options?: JsonLayoutOptions): string;
|
|
83
112
|
/** Absolute path of the committed artifact for a package root. */
|
|
84
113
|
export declare function pluginManifestPath(root?: string): string;
|
|
85
114
|
/**
|
|
@@ -28,6 +28,7 @@ import { readFileSync } from 'node:fs';
|
|
|
28
28
|
import { dirname, join, relative } from 'node:path';
|
|
29
29
|
import { repoRoot } from 'peaks-loop-shared/paths';
|
|
30
30
|
import { loadSkillRegistry } from '../skills/skill-registry.js';
|
|
31
|
+
import { DEFAULT_JSON_LAYOUT, renderJsonDocument } from './json-layout.js';
|
|
31
32
|
/** Where the generator writes, relative to the package root. */
|
|
32
33
|
export const PLUGIN_MANIFEST_RELATIVE_PATH = '.claude-plugin/marketplace.json';
|
|
33
34
|
/**
|
|
@@ -97,9 +98,43 @@ export function generatePluginManifest(manifest, skills) {
|
|
|
97
98
|
]
|
|
98
99
|
};
|
|
99
100
|
}
|
|
100
|
-
/**
|
|
101
|
-
|
|
102
|
-
|
|
101
|
+
/**
|
|
102
|
+
* The layout the repository's own prettier config asks for.
|
|
103
|
+
*
|
|
104
|
+
* The config file is the ONE source of truth for `printWidth`; a second copy of the
|
|
105
|
+
* number here would be a second decision, and the artifact would drift from the
|
|
106
|
+
* tool that checks it the first time either moved. Absent config falls back to
|
|
107
|
+
* prettier's own defaults.
|
|
108
|
+
*/
|
|
109
|
+
function jsonLayoutOf(manifest) {
|
|
110
|
+
return {
|
|
111
|
+
printWidth: manifest.prettier?.printWidth ?? DEFAULT_JSON_LAYOUT.printWidth,
|
|
112
|
+
tabWidth: manifest.prettier?.tabWidth ?? DEFAULT_JSON_LAYOUT.tabWidth
|
|
113
|
+
};
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* The layout the repository's own prettier config asks for, read from the ROOT
|
|
117
|
+
* package.json. Exported so the guard that checks the artifact resolves the layout
|
|
118
|
+
* the same way the renderer does — two resolutions would be two decisions.
|
|
119
|
+
*/
|
|
120
|
+
export function repositoryJsonLayout() {
|
|
121
|
+
return jsonLayoutOf(loadPackageManifest());
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* The artifact's bytes, newline-terminated — the same serialization contract as the
|
|
125
|
+
* whitelist, in the layout prettier produces for JSON.
|
|
126
|
+
*
|
|
127
|
+
* `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
|
|
128
|
+
* regardless of width, so the committed artifact was not prettier-clean. The shape
|
|
129
|
+
* is now computed by `json-layout.ts`, which implements prettier's JSON rules with
|
|
130
|
+
* ZERO dependencies — `prettier` is a devDependency, and this module ships to
|
|
131
|
+
* consumers inside `dist/**`, so it must not depend on it.
|
|
132
|
+
*
|
|
133
|
+
* The default layout is the repository's own, read from the root `package.json`;
|
|
134
|
+
* a caller rendering for another root passes the layout it resolved there.
|
|
135
|
+
*/
|
|
136
|
+
export function serializePluginManifest(manifest, options = repositoryJsonLayout()) {
|
|
137
|
+
return renderJsonDocument(manifest, options);
|
|
103
138
|
}
|
|
104
139
|
/** Absolute path of the committed artifact for a package root. */
|
|
105
140
|
export function pluginManifestPath(root = repoRoot) {
|
|
@@ -122,5 +157,6 @@ export async function renderPluginManifest(root = repoRoot) {
|
|
|
122
157
|
const named = skills.failures.map((failure) => failure.skillPath).join(', ');
|
|
123
158
|
throw new Error(`Refusing to render the plugin manifest: unreadable skill(s): ${named}`);
|
|
124
159
|
}
|
|
125
|
-
|
|
160
|
+
const pkg = loadPackageManifest(root);
|
|
161
|
+
return serializePluginManifest(generatePluginManifest(pkg, skills.skills), jsonLayoutOf(pkg));
|
|
126
162
|
}
|
|
@@ -2,13 +2,18 @@
|
|
|
2
2
|
* `src/services/observability/aggregation-helpers.ts`
|
|
3
3
|
*
|
|
4
4
|
* The event-detail readers the aggregations in `aggregation.ts` are built on
|
|
5
|
-
* (category test, `detail` field extraction, timestamp difference)
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
5
|
+
* (category test, `detail` field extraction, timestamp difference) and the
|
|
6
|
+
* two event-source helpers the CLI calls. Moved verbatim (wave 3, file-size
|
|
7
|
+
* cap campaign) so the aggregation module stays under the 300 raw-line cap.
|
|
8
|
+
* The first four were module-private before the move and are NOT re-exported
|
|
9
|
+
* from `aggregation.ts`; the two event-source helpers were public and are
|
|
10
|
+
* re-exported there, so that module's public surface is unchanged.
|
|
11
|
+
*
|
|
12
|
+
* The per-slice repair-cycle count that used to live here moved to
|
|
13
|
+
* `repair-cycle-metric.ts`: the version-1 counter this file carried counted
|
|
14
|
+
* QA's own state transitions, not repair loops, and the corrected metric
|
|
15
|
+
* needs its own module to keep the version marker and the legacy count
|
|
16
|
+
* together.
|
|
12
17
|
*/
|
|
13
18
|
import { type ObservabilityEvent } from './observability-service.js';
|
|
14
19
|
export declare function isSliceTransition(event: ObservabilityEvent): event is ObservabilityEvent & {
|
|
@@ -17,6 +22,5 @@ export declare function isSliceTransition(event: ObservabilityEvent): event is O
|
|
|
17
22
|
export declare function artifactRole(event: ObservabilityEvent): string;
|
|
18
23
|
export declare function transitionTo(event: ObservabilityEvent): string | null;
|
|
19
24
|
export declare function durationMsBetween(firstTs: string, lastTs: string): number;
|
|
20
|
-
export declare function computeRepairCyclesBySlice(events: readonly ObservabilityEvent[]): Map<string, number>;
|
|
21
25
|
export declare function readAllSessionEvents(projectRoot: string): ObservabilityEvent[];
|
|
22
26
|
export declare function readSessionEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];
|
|
@@ -2,13 +2,18 @@
|
|
|
2
2
|
* `src/services/observability/aggregation-helpers.ts`
|
|
3
3
|
*
|
|
4
4
|
* The event-detail readers the aggregations in `aggregation.ts` are built on
|
|
5
|
-
* (category test, `detail` field extraction, timestamp difference)
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
5
|
+
* (category test, `detail` field extraction, timestamp difference) and the
|
|
6
|
+
* two event-source helpers the CLI calls. Moved verbatim (wave 3, file-size
|
|
7
|
+
* cap campaign) so the aggregation module stays under the 300 raw-line cap.
|
|
8
|
+
* The first four were module-private before the move and are NOT re-exported
|
|
9
|
+
* from `aggregation.ts`; the two event-source helpers were public and are
|
|
10
|
+
* re-exported there, so that module's public surface is unchanged.
|
|
11
|
+
*
|
|
12
|
+
* The per-slice repair-cycle count that used to live here moved to
|
|
13
|
+
* `repair-cycle-metric.ts`: the version-1 counter this file carried counted
|
|
14
|
+
* QA's own state transitions, not repair loops, and the corrected metric
|
|
15
|
+
* needs its own module to keep the version marker and the legacy count
|
|
16
|
+
* together.
|
|
12
17
|
*/
|
|
13
18
|
import { readObservabilityEvents } from './observability-service.js';
|
|
14
19
|
import { listSessionDirsWithMetrics } from './jsonl-store.js';
|
|
@@ -31,24 +36,6 @@ export function durationMsBetween(firstTs, lastTs) {
|
|
|
31
36
|
}
|
|
32
37
|
return Math.max(0, b - a);
|
|
33
38
|
}
|
|
34
|
-
export function computeRepairCyclesBySlice(events) {
|
|
35
|
-
// Repair cycle = each rd → qa transition within one slice (proxy for the
|
|
36
|
-
// RD→QA→RD loop). For each slice we count qa transitions that follow an
|
|
37
|
-
// rd transition. Multiple qa transitions on the same slice are capped by
|
|
38
|
-
// REPAIR_CYCLE_CAP at the report level — the per-slice count here is the
|
|
39
|
-
// raw observation count.
|
|
40
|
-
const cyclesBySlice = new Map();
|
|
41
|
-
for (const event of events) {
|
|
42
|
-
if (!isSliceTransition(event))
|
|
43
|
-
continue;
|
|
44
|
-
const rid = event.sliceRid;
|
|
45
|
-
const role = artifactRole(event);
|
|
46
|
-
if (role === 'qa') {
|
|
47
|
-
cyclesBySlice.set(rid, (cyclesBySlice.get(rid) ?? 0) + 1);
|
|
48
|
-
}
|
|
49
|
-
}
|
|
50
|
-
return cyclesBySlice;
|
|
51
|
-
}
|
|
52
39
|
export function readAllSessionEvents(projectRoot) {
|
|
53
40
|
const sessions = listSessionDirsWithMetrics(projectRoot);
|
|
54
41
|
const all = [];
|
|
@@ -34,15 +34,55 @@ export type FanoutBreakdown = {
|
|
|
34
34
|
total: number;
|
|
35
35
|
perRole: Record<ObservabilitySubagentRole, number>;
|
|
36
36
|
};
|
|
37
|
+
/**
|
|
38
|
+
* The v1 convention, kept alive under a name that says what it is. It counts
|
|
39
|
+
* slice-transition events whose `detail.artifactRole === 'qa'` — QA's own
|
|
40
|
+
* internal state transitions, doubled by the duplicate emission, and NOT a
|
|
41
|
+
* repair-cycle count. It exists so the v1 and v2 numbers can be compared side
|
|
42
|
+
* by side instead of being compared by accident.
|
|
43
|
+
*/
|
|
44
|
+
export type LegacyQaEventCount = {
|
|
45
|
+
metric: 'qa-role-transition-event-count';
|
|
46
|
+
metricVersion: 1;
|
|
47
|
+
note: string;
|
|
48
|
+
total: number;
|
|
49
|
+
peak: number;
|
|
50
|
+
capHitCount: number;
|
|
51
|
+
perSlice: Array<{
|
|
52
|
+
sliceRid: string;
|
|
53
|
+
eventCount: number;
|
|
54
|
+
}>;
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* QA phases, reported separately from repair cycles: `qa-handoff →
|
|
58
|
+
* verdict-issued → qa-handoff` is a QA round, not an RD rework.
|
|
59
|
+
*/
|
|
60
|
+
export type QaRoundSummary = {
|
|
61
|
+
metric: 'qa-rounds';
|
|
62
|
+
total: number;
|
|
63
|
+
peak: number;
|
|
64
|
+
perSlice: Array<{
|
|
65
|
+
sliceRid: string;
|
|
66
|
+
roundCount: number;
|
|
67
|
+
}>;
|
|
68
|
+
};
|
|
37
69
|
export type RepairCycleReport = {
|
|
70
|
+
metric: 'repair-cycles';
|
|
71
|
+
/** Which convention produced the numbers below. */
|
|
72
|
+
metricVersion: number;
|
|
73
|
+
/** What the metric counts, in one sentence. */
|
|
74
|
+
definition: string;
|
|
38
75
|
totalCycles: number;
|
|
39
76
|
cap: number;
|
|
40
77
|
capHit: boolean;
|
|
78
|
+
/** Slices at or over the cap — computed from the v2 metric. */
|
|
41
79
|
capHitCount: number;
|
|
42
80
|
perSlice: Array<{
|
|
43
81
|
sliceRid: string;
|
|
44
82
|
cycleCount: number;
|
|
45
83
|
}>;
|
|
84
|
+
qaRounds: QaRoundSummary;
|
|
85
|
+
legacyQaEventCount: LegacyQaEventCount;
|
|
46
86
|
};
|
|
47
87
|
export declare const TERMINAL_HAPPY_STATES: ReadonlySet<string>;
|
|
48
88
|
export declare const TERMINAL_FAIL_STATES: ReadonlySet<string>;
|
|
@@ -16,8 +16,9 @@
|
|
|
16
16
|
import { type ObservabilityEvent } from './observability-service.js';
|
|
17
17
|
import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
|
|
18
18
|
export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
|
|
19
|
+
export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
|
|
19
20
|
export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
|
|
20
|
-
export type { DashboardMetrics, FanoutBreakdown, Period, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
21
|
+
export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
21
22
|
export declare function aggregateStatus(events: readonly ObservabilityEvent[]): StatusAggregate;
|
|
22
23
|
export declare function aggregateSlices(events: readonly ObservabilityEvent[]): SliceRollup[];
|
|
23
24
|
export declare function aggregateFanout(events: readonly ObservabilityEvent[]): FanoutBreakdown;
|
|
@@ -14,16 +14,19 @@
|
|
|
14
14
|
* builds the read-side surface so Slice C is purely additive.
|
|
15
15
|
*/
|
|
16
16
|
import { readObservabilityEvents } from './observability-service.js';
|
|
17
|
-
import {
|
|
18
|
-
import {
|
|
17
|
+
import { TERMINAL_FAIL_STATES, TERMINAL_HAPPY_STATES, ZERO_FANOUT } from './aggregation-types.js';
|
|
18
|
+
import { durationMsBetween, isSliceTransition, transitionTo } from './aggregation-helpers.js';
|
|
19
|
+
import { buildRepairCycleReport, computeSliceRepairMetrics } from './repair-cycle-metric.js';
|
|
19
20
|
// The result shapes and their data (terminal states, repair-loop cap, zeroed
|
|
20
|
-
// fan-out row) live in `aggregation-types.ts`; the event-detail readers
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
//
|
|
24
|
-
//
|
|
25
|
-
//
|
|
21
|
+
// fan-out row) live in `aggregation-types.ts`; the event-detail readers and
|
|
22
|
+
// the event-source helpers live in `aggregation-helpers.ts` (wave-3 file-size
|
|
23
|
+
// cap split; declarations moved verbatim). The repair-cycle METRIC lives in
|
|
24
|
+
// `repair-cycle-metric.ts` — version 2 of it, with the version-1 count kept
|
|
25
|
+
// beside it under its own name. Every PUBLIC name is re-exported below so
|
|
26
|
+
// importers keep resolving it from `aggregation.js` unchanged; the
|
|
27
|
+
// module-private readers are imported for use here and not re-exported.
|
|
26
28
|
export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
|
|
29
|
+
export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
|
|
27
30
|
export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
|
|
28
31
|
// ----- per-slice rollup (shared by status + slices queries) -----
|
|
29
32
|
function rollupSlices(events) {
|
|
@@ -69,10 +72,10 @@ function rollupSlices(events) {
|
|
|
69
72
|
// ----- public aggregations -----
|
|
70
73
|
export function aggregateStatus(events) {
|
|
71
74
|
const bySlice = rollupSlices(events);
|
|
72
|
-
const
|
|
75
|
+
const metrics = computeSliceRepairMetrics(events);
|
|
73
76
|
let repairCyclePeak = 0;
|
|
74
77
|
for (const rollup of bySlice.values()) {
|
|
75
|
-
const cycles =
|
|
78
|
+
const cycles = metrics.get(rollup.sliceRid)?.repairCycles ?? 0;
|
|
76
79
|
rollup.repairCycleCount = cycles;
|
|
77
80
|
if (cycles > repairCyclePeak)
|
|
78
81
|
repairCyclePeak = cycles;
|
|
@@ -91,9 +94,9 @@ export function aggregateStatus(events) {
|
|
|
91
94
|
}
|
|
92
95
|
export function aggregateSlices(events) {
|
|
93
96
|
const bySlice = rollupSlices(events);
|
|
94
|
-
const
|
|
97
|
+
const metrics = computeSliceRepairMetrics(events);
|
|
95
98
|
for (const rollup of bySlice.values()) {
|
|
96
|
-
rollup.repairCycleCount =
|
|
99
|
+
rollup.repairCycleCount = metrics.get(rollup.sliceRid)?.repairCycles ?? 0;
|
|
97
100
|
}
|
|
98
101
|
return Array.from(bySlice.values()).sort((a, b) => a.sliceRid.localeCompare(b.sliceRid));
|
|
99
102
|
}
|
|
@@ -111,19 +114,7 @@ export function aggregateFanout(events) {
|
|
|
111
114
|
return { total, perRole };
|
|
112
115
|
}
|
|
113
116
|
export function aggregateRepairCycles(events) {
|
|
114
|
-
|
|
115
|
-
const perSlice = Array.from(cyclesBySlice.entries())
|
|
116
|
-
.map(([sliceRid, cycleCount]) => ({ sliceRid, cycleCount }))
|
|
117
|
-
.sort((a, b) => a.sliceRid.localeCompare(b.sliceRid));
|
|
118
|
-
const totalCycles = perSlice.reduce((sum, row) => sum + row.cycleCount, 0);
|
|
119
|
-
const capHitCount = perSlice.filter((row) => row.cycleCount >= REPAIR_CYCLE_CAP).length;
|
|
120
|
-
return {
|
|
121
|
-
totalCycles,
|
|
122
|
-
cap: REPAIR_CYCLE_CAP,
|
|
123
|
-
capHit: capHitCount > 0,
|
|
124
|
-
capHitCount,
|
|
125
|
-
perSlice
|
|
126
|
-
};
|
|
117
|
+
return buildRepairCycleReport(events);
|
|
127
118
|
}
|
|
128
119
|
export function periodStartIso(period, now = () => new Date()) {
|
|
129
120
|
const d = now();
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/repair-cycle-metric.ts`
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS MODULE EXISTS — the measured defect that forced the metric to
|
|
5
|
+
* change.
|
|
6
|
+
*
|
|
7
|
+
* The repair-cycle counter that used to live in `aggregation-helpers.ts`
|
|
8
|
+
* counted every slice-transition event whose `detail.artifactRole === 'qa'`.
|
|
9
|
+
* That is not a repair-cycle count: it counts QA's OWN internal state
|
|
10
|
+
* transitions, and it counts every transition TWICE because
|
|
11
|
+
* `peaks request transition` emits one event without `detail.from` and a
|
|
12
|
+
* second one with it. Measured over this repo's own recorded history
|
|
13
|
+
* (10 session dirs, 108 slices, 1102 slice-transition events) the old
|
|
14
|
+
* counter put 82 of the 108 slices at or over the cap of 3, while exactly
|
|
15
|
+
* ONE slice ever really reworked — and it reworked FIVE times.
|
|
16
|
+
* The other 81 alarms were a measurement artifact, not rework.
|
|
17
|
+
*
|
|
18
|
+
* So the metric is VERSIONED. Version 1 is the qa-event count — it is kept,
|
|
19
|
+
* under the name `legacyQaEventCount`, so the old number and the new number
|
|
20
|
+
* can be read side by side instead of being compared by accident. Version 2
|
|
21
|
+
* is the repair-cycle count computed here.
|
|
22
|
+
*
|
|
23
|
+
* THE v2 DEFINITION. A repair cycle = the slice's artifact RETURNS to an RD
|
|
24
|
+
* work state (`draft` | `spec-locked` | `implemented`) after it had entered a
|
|
25
|
+
* QA phase (`running` | `verdict-issued`). The state vocabulary is the one
|
|
26
|
+
* `ALLOWED_STATES_PER_ROLE` declares in
|
|
27
|
+
* `src/services/artifacts/request-artifact-state-helpers.ts`: `qa-handoff`
|
|
28
|
+
* is an RD state, so the normal closing hops `verdict-issued → qa-handoff` and
|
|
29
|
+
* `qa-handoff → handed-off` are the happy path, not rework.
|
|
30
|
+
*
|
|
31
|
+
* This is NOT the same measurement as
|
|
32
|
+
* `src/services/artifacts/repair-cycle-service.ts`, which counts the
|
|
33
|
+
* `QA return-to-rd cycle N` notes inside a request artifact. That one is the
|
|
34
|
+
* artifact contract's own record; this one is reconstructed from the
|
|
35
|
+
* observability event stream. The two are reported separately and are never
|
|
36
|
+
* merged.
|
|
37
|
+
*/
|
|
38
|
+
import { type RepairCycleReport } from './aggregation-types.js';
|
|
39
|
+
import type { ObservabilityEvent } from './observability-service.js';
|
|
40
|
+
/**
|
|
41
|
+
* Version 1 was never versioned — it silently counted qa-role events.
|
|
42
|
+
* Version 2 is the repair-cycle count. A consumer that reads
|
|
43
|
+
* `metricVersion` can therefore tell which convention produced the numbers
|
|
44
|
+
* printed next to it.
|
|
45
|
+
*/
|
|
46
|
+
export declare const REPAIR_CYCLE_METRIC_VERSION = 2;
|
|
47
|
+
/** What the v2 number counts, in one sentence, for every consumer that prints it. */
|
|
48
|
+
export declare const REPAIR_CYCLE_METRIC_DEFINITION: string;
|
|
49
|
+
/** What the v1 number counts, and why it must never be read as a repair-cycle count. */
|
|
50
|
+
export declare const LEGACY_QA_EVENT_COUNT_NOTE: string;
|
|
51
|
+
/** The three numbers one slice carries. */
|
|
52
|
+
export type SliceRepairMetrics = {
|
|
53
|
+
/** v2: how many times the slice came back to an RD work state after a QA phase. */
|
|
54
|
+
repairCycles: number;
|
|
55
|
+
/** v2: how many QA phases the slice entered. */
|
|
56
|
+
qaRounds: number;
|
|
57
|
+
/** v1: how many qa-role slice-transition events the slice emitted. */
|
|
58
|
+
legacyQaEventCount: number;
|
|
59
|
+
};
|
|
60
|
+
/** The three numbers, per slice, over the whole event stream. */
|
|
61
|
+
export declare function computeSliceRepairMetrics(events: readonly ObservabilityEvent[]): Map<string, SliceRepairMetrics>;
|
|
62
|
+
/**
|
|
63
|
+
* The repair-cycle report. `capHitCount` is computed from the v2 metric; the
|
|
64
|
+
* v1 count rides along under its own name so the two conventions can be
|
|
65
|
+
* compared rather than confused.
|
|
66
|
+
*/
|
|
67
|
+
export declare function buildRepairCycleReport(events: readonly ObservabilityEvent[]): RepairCycleReport;
|