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
|
@@ -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
|
}
|
|
@@ -16,6 +16,16 @@ export type StatusAggregate = {
|
|
|
16
16
|
totalSlices: number;
|
|
17
17
|
successCount: number;
|
|
18
18
|
failCount: number;
|
|
19
|
+
/**
|
|
20
|
+
* Slices that reached a state which is neither a success terminal state nor
|
|
21
|
+
* a terminal failure — the ones stuck mid-flight, e.g. at `qa-handoff`.
|
|
22
|
+
*
|
|
23
|
+
* The three outcome counts partition the slice set, so
|
|
24
|
+
* `successCount + failCount + stalledCount === totalSlices` holds for every
|
|
25
|
+
* event set. A slice whose transitions recorded no final state at all also
|
|
26
|
+
* lands here: it reached no terminal outcome either.
|
|
27
|
+
*/
|
|
28
|
+
readonly stalledCount: number;
|
|
19
29
|
repairCyclePeak: number;
|
|
20
30
|
fanoutCostTotal: number;
|
|
21
31
|
};
|
|
@@ -30,6 +40,17 @@ export type SliceRollup = {
|
|
|
30
40
|
repairCycleCount: number;
|
|
31
41
|
success: boolean;
|
|
32
42
|
};
|
|
43
|
+
/**
|
|
44
|
+
* How one slice ended.
|
|
45
|
+
*
|
|
46
|
+
* The three outcomes PARTITION the slice set: a slice that reached a
|
|
47
|
+
* terminal success state, a slice that reached a terminal failure state, and
|
|
48
|
+
* a slice that reached NEITHER — it advanced partway and stopped (at
|
|
49
|
+
* `qa-handoff`, typically). `stalled` is not a failure: the work was never
|
|
50
|
+
* concluded, and the counts must say so rather than drop the slice from the
|
|
51
|
+
* accounting.
|
|
52
|
+
*/
|
|
53
|
+
export type SliceOutcome = 'success' | 'failed' | 'stalled';
|
|
33
54
|
export type FanoutBreakdown = {
|
|
34
55
|
total: number;
|
|
35
56
|
perRole: Record<ObservabilitySubagentRole, number>;
|
|
@@ -14,11 +14,21 @@
|
|
|
14
14
|
* builds the read-side surface so Slice C is purely additive.
|
|
15
15
|
*/
|
|
16
16
|
import { type ObservabilityEvent } from './observability-service.js';
|
|
17
|
-
import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
|
|
17
|
+
import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceOutcome, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
|
|
18
18
|
export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
|
|
19
19
|
export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
|
|
20
20
|
export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
|
|
21
|
-
export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
21
|
+
export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceOutcome, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
22
|
+
/**
|
|
23
|
+
* How one slice ended, from its rollup.
|
|
24
|
+
*
|
|
25
|
+
* ONE spelling of the three outcomes, shared by the status counts and by the
|
|
26
|
+
* report's slice table: a slice that reached a terminal success state, a slice
|
|
27
|
+
* that reached a terminal failure state, and a slice that reached NEITHER — it
|
|
28
|
+
* advanced partway and stopped (at `qa-handoff`, typically). The last is not a
|
|
29
|
+
* failure, so it is not counted as one and is not drawn as one.
|
|
30
|
+
*/
|
|
31
|
+
export declare function sliceOutcome(rollup: SliceRollup): SliceOutcome;
|
|
22
32
|
export declare function aggregateStatus(events: readonly ObservabilityEvent[]): StatusAggregate;
|
|
23
33
|
export declare function aggregateSlices(events: readonly ObservabilityEvent[]): SliceRollup[];
|
|
24
34
|
export declare function aggregateFanout(events: readonly ObservabilityEvent[]): FanoutBreakdown;
|
|
@@ -70,6 +70,22 @@ function rollupSlices(events) {
|
|
|
70
70
|
return bySlice;
|
|
71
71
|
}
|
|
72
72
|
// ----- public aggregations -----
|
|
73
|
+
/**
|
|
74
|
+
* How one slice ended, from its rollup.
|
|
75
|
+
*
|
|
76
|
+
* ONE spelling of the three outcomes, shared by the status counts and by the
|
|
77
|
+
* report's slice table: a slice that reached a terminal success state, a slice
|
|
78
|
+
* that reached a terminal failure state, and a slice that reached NEITHER — it
|
|
79
|
+
* advanced partway and stopped (at `qa-handoff`, typically). The last is not a
|
|
80
|
+
* failure, so it is not counted as one and is not drawn as one.
|
|
81
|
+
*/
|
|
82
|
+
export function sliceOutcome(rollup) {
|
|
83
|
+
if (rollup.success)
|
|
84
|
+
return 'success';
|
|
85
|
+
if (rollup.finalState !== null && TERMINAL_FAIL_STATES.has(rollup.finalState))
|
|
86
|
+
return 'failed';
|
|
87
|
+
return 'stalled';
|
|
88
|
+
}
|
|
73
89
|
export function aggregateStatus(events) {
|
|
74
90
|
const bySlice = rollupSlices(events);
|
|
75
91
|
const metrics = computeSliceRepairMetrics(events);
|
|
@@ -80,14 +96,22 @@ export function aggregateStatus(events) {
|
|
|
80
96
|
if (cycles > repairCyclePeak)
|
|
81
97
|
repairCyclePeak = cycles;
|
|
82
98
|
}
|
|
83
|
-
|
|
84
|
-
|
|
99
|
+
// The three outcome buckets come from the ONE outcome spelling above, so
|
|
100
|
+
// they partition the slice set: every slice lands in exactly one bucket and
|
|
101
|
+
// `successCount + failCount + stalledCount === totalSlices` holds for every
|
|
102
|
+
// event set. Before the third bucket existed, a slice stuck at `qa-handoff`
|
|
103
|
+
// was in NEITHER the success nor the fail count and the summary reported
|
|
104
|
+
// fewer outcomes than the slice table showed rows.
|
|
105
|
+
const successCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'success').length;
|
|
106
|
+
const failCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'failed').length;
|
|
107
|
+
const stalledCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'stalled').length;
|
|
85
108
|
const fanoutCostTotal = events.filter((e) => e.category === 'dispatch').length;
|
|
86
109
|
return {
|
|
87
110
|
totalEvents: events.length,
|
|
88
111
|
totalSlices: bySlice.size,
|
|
89
112
|
successCount,
|
|
90
113
|
failCount,
|
|
114
|
+
stalledCount,
|
|
91
115
|
repairCyclePeak,
|
|
92
116
|
fanoutCostTotal
|
|
93
117
|
};
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/compliance-judge.ts`
|
|
3
|
+
*
|
|
4
|
+
* The judge: given a compliance spec and a way to ask whether an artifact
|
|
5
|
+
* exists, report which declared steps actually ran.
|
|
6
|
+
*
|
|
7
|
+
* WHY A JUDGE AND NOT A SCOREBOARD. A pass rate says "the slice passed"; a
|
|
8
|
+
* compliance rate says "the checks the skill PROMISED ran". The difference is
|
|
9
|
+
* the point of the campaign: a slice can pass its gate while a step the skill
|
|
10
|
+
* declared never happened, and only the second reading sees that.
|
|
11
|
+
*
|
|
12
|
+
* THE JUDGE IS PURE. It never touches a filesystem: whether an artifact exists
|
|
13
|
+
* is asked through the `exists` callback the caller supplies. That is what
|
|
14
|
+
* makes one spec judgeable against a real workspace, a fixture, or a
|
|
15
|
+
* hypothetical — and it is why the rules below are statements about RULES
|
|
16
|
+
* rather than about a machine's state.
|
|
17
|
+
*
|
|
18
|
+
* THE DEMOTION RULE, AND WHY IT IS A FIXPOINT. A step that declares
|
|
19
|
+
* `afterStep: X` cannot be credited on the strength of its own artifact when X
|
|
20
|
+
* did not run: the audit that exists without the handoff it read is not
|
|
21
|
+
* evidence of an audit. Demoting one step can invalidate whatever depended on
|
|
22
|
+
* it, so the demotion is applied repeatedly until nothing changes — and since
|
|
23
|
+
* demotion only ever removes a pass, the loop terminates.
|
|
24
|
+
*
|
|
25
|
+
* STEP IDS MUST BE UNIQUE INSIDE A SPEC, AND THE JUDGE ENFORCES IT. The
|
|
26
|
+
* demotion looks a prerequisite up by id, so two steps sharing one id would be
|
|
27
|
+
* judged against each other — and each would overwrite the other's presence
|
|
28
|
+
* in the judge's bookkeeping, so both would report the same verdict. That is
|
|
29
|
+
* a silently wrong compliance number, which is the exact failure this
|
|
30
|
+
* campaign exists to prevent, so a spec that declares one id twice is
|
|
31
|
+
* REJECTED with an error naming the id rather than scored.
|
|
32
|
+
*/
|
|
33
|
+
import type { ComplianceSpec } from './compliance-spec.js';
|
|
34
|
+
/** What the judge concluded about one declared step. */
|
|
35
|
+
export type StepResult = {
|
|
36
|
+
/** The step's id, so a reader can find it in the spec. */
|
|
37
|
+
readonly stepId: string;
|
|
38
|
+
/** Whether the step's artifact was there. */
|
|
39
|
+
readonly executed: boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Why the step did not execute. Present exactly when `executed` is false;
|
|
42
|
+
* absent when it is true, because a passing step has nothing to explain.
|
|
43
|
+
*/
|
|
44
|
+
readonly failureReason?: string;
|
|
45
|
+
};
|
|
46
|
+
/** The verdict for one spec. */
|
|
47
|
+
export type ComplianceResult = {
|
|
48
|
+
/** The spec's id. */
|
|
49
|
+
readonly specId: string;
|
|
50
|
+
/** One entry per declared step, in the order the spec declares them. */
|
|
51
|
+
readonly steps: readonly StepResult[];
|
|
52
|
+
/**
|
|
53
|
+
* The share of REQUIRED steps that executed. A spec that declares no
|
|
54
|
+
* required step demonstrates no compliance, so the rate is 0 rather than a
|
|
55
|
+
* vacuous 1: the reading that lets a spec declaring nothing read as
|
|
56
|
+
* perfect compliance is the one this metric exists to refuse.
|
|
57
|
+
*/
|
|
58
|
+
readonly complianceRate: number;
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Judge one spec.
|
|
62
|
+
*
|
|
63
|
+
* @param spec the declared steps to judge.
|
|
64
|
+
* @param exists asked whether a session-relative artifact path is present.
|
|
65
|
+
* THE PATH ARRIVES WITH ITS `<rid>` PLACEHOLDER UNRESOLVED. The judge hands
|
|
66
|
+
* the declared path through verbatim; the CALLER substitutes the request id
|
|
67
|
+
* before probing the filesystem. A caller that probes the raw string gets
|
|
68
|
+
* the literal `<rid>` as a path, every step misses, and the rate reads 0
|
|
69
|
+
* without a single error — so the substitution is the caller's job, and it
|
|
70
|
+
* is stated here because that is where the callback is declared.
|
|
71
|
+
*
|
|
72
|
+
* @throws Error when two steps of the spec share one id. The judge's
|
|
73
|
+
* bookkeeping is keyed by step id, so a repeated id would make two steps
|
|
74
|
+
* overwrite each other's presence and report the same verdict — a silently
|
|
75
|
+
* wrong compliance number. A malformed spec is refused rather than scored.
|
|
76
|
+
*/
|
|
77
|
+
export declare function judgeCompliance(spec: ComplianceSpec, exists: (artifactPath: string) => boolean): ComplianceResult;
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/compliance-judge.ts`
|
|
3
|
+
*
|
|
4
|
+
* The judge: given a compliance spec and a way to ask whether an artifact
|
|
5
|
+
* exists, report which declared steps actually ran.
|
|
6
|
+
*
|
|
7
|
+
* WHY A JUDGE AND NOT A SCOREBOARD. A pass rate says "the slice passed"; a
|
|
8
|
+
* compliance rate says "the checks the skill PROMISED ran". The difference is
|
|
9
|
+
* the point of the campaign: a slice can pass its gate while a step the skill
|
|
10
|
+
* declared never happened, and only the second reading sees that.
|
|
11
|
+
*
|
|
12
|
+
* THE JUDGE IS PURE. It never touches a filesystem: whether an artifact exists
|
|
13
|
+
* is asked through the `exists` callback the caller supplies. That is what
|
|
14
|
+
* makes one spec judgeable against a real workspace, a fixture, or a
|
|
15
|
+
* hypothetical — and it is why the rules below are statements about RULES
|
|
16
|
+
* rather than about a machine's state.
|
|
17
|
+
*
|
|
18
|
+
* THE DEMOTION RULE, AND WHY IT IS A FIXPOINT. A step that declares
|
|
19
|
+
* `afterStep: X` cannot be credited on the strength of its own artifact when X
|
|
20
|
+
* did not run: the audit that exists without the handoff it read is not
|
|
21
|
+
* evidence of an audit. Demoting one step can invalidate whatever depended on
|
|
22
|
+
* it, so the demotion is applied repeatedly until nothing changes — and since
|
|
23
|
+
* demotion only ever removes a pass, the loop terminates.
|
|
24
|
+
*
|
|
25
|
+
* STEP IDS MUST BE UNIQUE INSIDE A SPEC, AND THE JUDGE ENFORCES IT. The
|
|
26
|
+
* demotion looks a prerequisite up by id, so two steps sharing one id would be
|
|
27
|
+
* judged against each other — and each would overwrite the other's presence
|
|
28
|
+
* in the judge's bookkeeping, so both would report the same verdict. That is
|
|
29
|
+
* a silently wrong compliance number, which is the exact failure this
|
|
30
|
+
* campaign exists to prevent, so a spec that declares one id twice is
|
|
31
|
+
* REJECTED with an error naming the id rather than scored.
|
|
32
|
+
*/
|
|
33
|
+
/**
|
|
34
|
+
* Judge one spec.
|
|
35
|
+
*
|
|
36
|
+
* @param spec the declared steps to judge.
|
|
37
|
+
* @param exists asked whether a session-relative artifact path is present.
|
|
38
|
+
* THE PATH ARRIVES WITH ITS `<rid>` PLACEHOLDER UNRESOLVED. The judge hands
|
|
39
|
+
* the declared path through verbatim; the CALLER substitutes the request id
|
|
40
|
+
* before probing the filesystem. A caller that probes the raw string gets
|
|
41
|
+
* the literal `<rid>` as a path, every step misses, and the rate reads 0
|
|
42
|
+
* without a single error — so the substitution is the caller's job, and it
|
|
43
|
+
* is stated here because that is where the callback is declared.
|
|
44
|
+
*
|
|
45
|
+
* @throws Error when two steps of the spec share one id. The judge's
|
|
46
|
+
* bookkeeping is keyed by step id, so a repeated id would make two steps
|
|
47
|
+
* overwrite each other's presence and report the same verdict — a silently
|
|
48
|
+
* wrong compliance number. A malformed spec is refused rather than scored.
|
|
49
|
+
*/
|
|
50
|
+
export function judgeCompliance(spec, exists) {
|
|
51
|
+
assertUniqueStepIds(spec);
|
|
52
|
+
const executed = new Map();
|
|
53
|
+
const reasons = new Map();
|
|
54
|
+
for (const step of spec.steps) {
|
|
55
|
+
const present = exists(step.verify.artifactExists);
|
|
56
|
+
executed.set(step.id, present);
|
|
57
|
+
if (!present) {
|
|
58
|
+
reasons.set(step.id, `missing artifact: ${step.verify.artifactExists}`);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
demoteUnsatisfiedPrerequisites(spec, executed, reasons);
|
|
62
|
+
const steps = spec.steps.map((step) => {
|
|
63
|
+
const ran = executed.get(step.id) === true;
|
|
64
|
+
const reason = reasons.get(step.id);
|
|
65
|
+
if (ran || reason === undefined) {
|
|
66
|
+
return { stepId: step.id, executed: ran };
|
|
67
|
+
}
|
|
68
|
+
return { stepId: step.id, executed: ran, failureReason: reason };
|
|
69
|
+
});
|
|
70
|
+
const required = spec.steps.filter((step) => step.required);
|
|
71
|
+
const executedRequired = required.filter((step) => executed.get(step.id) === true).length;
|
|
72
|
+
const complianceRate = required.length === 0 ? 0 : executedRequired / required.length;
|
|
73
|
+
return { specId: spec.id, steps, complianceRate };
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* Refuse a spec that declares the same step id twice.
|
|
77
|
+
*
|
|
78
|
+
* THE REFUSAL IS THE POINT. The judge's bookkeeping is keyed by step id, so
|
|
79
|
+
* two steps sharing one id would overwrite each other's presence and then
|
|
80
|
+
* report the SAME verdict — one of them would be credited on the other's
|
|
81
|
+
* artifact, and the compliance rate would be wrong without anything saying so.
|
|
82
|
+
* A silently wrong compliance number is the exact failure this campaign
|
|
83
|
+
* exists to prevent, so the malformed spec is refused instead of scored.
|
|
84
|
+
*/
|
|
85
|
+
function assertUniqueStepIds(spec) {
|
|
86
|
+
const seen = new Set();
|
|
87
|
+
for (const step of spec.steps) {
|
|
88
|
+
if (seen.has(step.id)) {
|
|
89
|
+
throw new Error(`compliance spec "${spec.id}" declares the step id "${step.id}" more than once; ` +
|
|
90
|
+
'step ids must be unique so each result names exactly one step');
|
|
91
|
+
}
|
|
92
|
+
seen.add(step.id);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Demote every step whose prerequisite did not execute, until nothing changes.
|
|
97
|
+
*
|
|
98
|
+
* A step names its prerequisite by id, and the prerequisite may be declared
|
|
99
|
+
* LATER in the spec — which is why this is a fixpoint rather than a single
|
|
100
|
+
* pass in declaration order. A prerequisite the spec does not declare is
|
|
101
|
+
* unsatisfied by definition: a step cannot be credited on the strength of a
|
|
102
|
+
* prerequisite nobody can show.
|
|
103
|
+
*
|
|
104
|
+
* THE PREREQUISITE'S OWN `required` FLAG DOES NOT MATTER HERE. A step is
|
|
105
|
+
* demoted whenever its prerequisite did not execute, even when that
|
|
106
|
+
* prerequisite is optional: an optional step that did not run is not a
|
|
107
|
+
* failure, but the step that was supposed to come AFTER it cannot be credited
|
|
108
|
+
* on its own artifact alone either, because the thing it was ordered against
|
|
109
|
+
* is not there. This is the conservative reading, and it is the same rule
|
|
110
|
+
* that keeps a required step honest when its prerequisite is missing; it is
|
|
111
|
+
* pinned by a test so it cannot change silently.
|
|
112
|
+
*/
|
|
113
|
+
function demoteUnsatisfiedPrerequisites(spec, executed, reasons) {
|
|
114
|
+
const declared = new Set(spec.steps.map((step) => step.id));
|
|
115
|
+
let changed = true;
|
|
116
|
+
while (changed) {
|
|
117
|
+
changed = false;
|
|
118
|
+
for (const step of spec.steps) {
|
|
119
|
+
const prerequisite = step.afterStep;
|
|
120
|
+
if (prerequisite === undefined)
|
|
121
|
+
continue;
|
|
122
|
+
if (executed.get(step.id) !== true)
|
|
123
|
+
continue;
|
|
124
|
+
if (prerequisite === step.id) {
|
|
125
|
+
executed.set(step.id, false);
|
|
126
|
+
reasons.set(step.id, `prerequisite step "${prerequisite}" is this step itself, so no order can be satisfied`);
|
|
127
|
+
changed = true;
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
if (!declared.has(prerequisite)) {
|
|
131
|
+
executed.set(step.id, false);
|
|
132
|
+
reasons.set(step.id, `prerequisite step "${prerequisite}" is not declared in this spec, so it cannot have run`);
|
|
133
|
+
changed = true;
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
if (executed.get(prerequisite) === true)
|
|
137
|
+
continue;
|
|
138
|
+
executed.set(step.id, false);
|
|
139
|
+
reasons.set(step.id, `prerequisite step "${prerequisite}" did not execute`);
|
|
140
|
+
changed = true;
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|