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,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/report-formatter-hotspots.ts`
|
|
3
|
+
*
|
|
4
|
+
* The hotspot section of the markdown report.
|
|
5
|
+
*
|
|
6
|
+
* WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
|
|
7
|
+
* 300-line cap, and the hotspot table does not fit beside the rest. The
|
|
8
|
+
* split follows the precedent in this directory: `aggregation.ts` keeps its
|
|
9
|
+
* readers in `aggregation-helpers.ts` for the same reason.
|
|
10
|
+
*
|
|
11
|
+
* WHY THE TABLES ARE SPLIT BY WHAT THE COUNT COUNTS. A hotspot row's count
|
|
12
|
+
* means DIFFERENT THINGS depending on how the row was known: an `exact` row
|
|
13
|
+
* counted the artifact being MISSING, and a reconstructed row counted the
|
|
14
|
+
* artifact being one of the CANDIDATES — one real failure contributes to
|
|
15
|
+
* every candidate the attribution could not narrow, so the number is candidate
|
|
16
|
+
* mentions, not failures. A single column cannot carry both meanings, so a
|
|
17
|
+
* reader of one column heading would have to know the rule to read the
|
|
18
|
+
* number under it.
|
|
19
|
+
*
|
|
20
|
+
* So there is ONE TABLE PER MEANING, and each column heading names what it
|
|
21
|
+
* counts: "times observed missing" and "candidate mentions". The confidence
|
|
22
|
+
* column stays as it is, so a reader can still see WHICH tier a row came
|
|
23
|
+
* from — the split makes the meaning visible without taking that away.
|
|
24
|
+
*
|
|
25
|
+
* WHY THE NOTE IS NOT THE WHOLE MECHANISM. The note says what the two
|
|
26
|
+
* meanings are; the column headings say which one a reader is looking at. A
|
|
27
|
+
* reader who skips the note still cannot take a candidate mention for a
|
|
28
|
+
* missing artifact.
|
|
29
|
+
*/
|
|
30
|
+
import { type HotspotRow } from './hotspot-shared.js';
|
|
31
|
+
/** The markdown for the hotspot section, including its heading. */
|
|
32
|
+
export declare function markdownHotspotTables(hotspots: readonly HotspotRow[]): string;
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/report-formatter-hotspots.ts`
|
|
3
|
+
*
|
|
4
|
+
* The hotspot section of the markdown report.
|
|
5
|
+
*
|
|
6
|
+
* WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
|
|
7
|
+
* 300-line cap, and the hotspot table does not fit beside the rest. The
|
|
8
|
+
* split follows the precedent in this directory: `aggregation.ts` keeps its
|
|
9
|
+
* readers in `aggregation-helpers.ts` for the same reason.
|
|
10
|
+
*
|
|
11
|
+
* WHY THE TABLES ARE SPLIT BY WHAT THE COUNT COUNTS. A hotspot row's count
|
|
12
|
+
* means DIFFERENT THINGS depending on how the row was known: an `exact` row
|
|
13
|
+
* counted the artifact being MISSING, and a reconstructed row counted the
|
|
14
|
+
* artifact being one of the CANDIDATES — one real failure contributes to
|
|
15
|
+
* every candidate the attribution could not narrow, so the number is candidate
|
|
16
|
+
* mentions, not failures. A single column cannot carry both meanings, so a
|
|
17
|
+
* reader of one column heading would have to know the rule to read the
|
|
18
|
+
* number under it.
|
|
19
|
+
*
|
|
20
|
+
* So there is ONE TABLE PER MEANING, and each column heading names what it
|
|
21
|
+
* counts: "times observed missing" and "candidate mentions". The confidence
|
|
22
|
+
* column stays as it is, so a reader can still see WHICH tier a row came
|
|
23
|
+
* from — the split makes the meaning visible without taking that away.
|
|
24
|
+
*
|
|
25
|
+
* WHY THE NOTE IS NOT THE WHOLE MECHANISM. The note says what the two
|
|
26
|
+
* meanings are; the column headings say which one a reader is looking at. A
|
|
27
|
+
* reader who skips the note still cannot take a candidate mention for a
|
|
28
|
+
* missing artifact.
|
|
29
|
+
*/
|
|
30
|
+
import { groupHotspotsByMeaning } from './hotspot-shared.js';
|
|
31
|
+
/** The markdown for the hotspot section, including its heading. */
|
|
32
|
+
export function markdownHotspotTables(hotspots) {
|
|
33
|
+
const lines = [];
|
|
34
|
+
lines.push('## Hotspots');
|
|
35
|
+
lines.push('');
|
|
36
|
+
if (hotspots.length === 0) {
|
|
37
|
+
lines.push('_No hotspot recorded for this period._');
|
|
38
|
+
lines.push('');
|
|
39
|
+
return lines.join('\n');
|
|
40
|
+
}
|
|
41
|
+
lines.push('_`exact` rows are MEASURED — the artifact was seen missing. `inferred`/`ambiguous` ' +
|
|
42
|
+
'rows are CANDIDATES recovered from a historical count: one real failure counts toward ' +
|
|
43
|
+
'EVERY candidate it could not narrow, so those counts are candidate mentions, not ' +
|
|
44
|
+
'failures._');
|
|
45
|
+
lines.push('');
|
|
46
|
+
// The SAME split the CLI's JSON payload uses, so the two surfaces cannot
|
|
47
|
+
// disagree about which rows are measurements and which are candidates.
|
|
48
|
+
const groups = groupHotspotsByMeaning(hotspots);
|
|
49
|
+
table(lines, groups.observedOmissions, 'Measured missing artifacts', 'times observed missing');
|
|
50
|
+
table(lines, groups.candidateMentions, 'Candidate artifacts', 'candidate mentions');
|
|
51
|
+
return lines.join('\n');
|
|
52
|
+
}
|
|
53
|
+
/** One table of rows, under a heading that names what its count counts. */
|
|
54
|
+
function table(lines, rows, heading, column) {
|
|
55
|
+
lines.push(`### ${heading}`);
|
|
56
|
+
lines.push('');
|
|
57
|
+
if (rows.length === 0) {
|
|
58
|
+
lines.push('_None._');
|
|
59
|
+
lines.push('');
|
|
60
|
+
return;
|
|
61
|
+
}
|
|
62
|
+
lines.push(`| artifact | owner skill | mode | confidence | ${column} |`);
|
|
63
|
+
lines.push('|---|---|---|---|---|');
|
|
64
|
+
for (const row of rows) {
|
|
65
|
+
lines.push(`| ${row.artifact} | ${row.ownerSkill ?? '—'} | ${row.kind} | ${row.confidence} | ${row.count} |`);
|
|
66
|
+
}
|
|
67
|
+
lines.push('');
|
|
68
|
+
// A row with no owner says WHY below the table: "no skill owns this" is a
|
|
69
|
+
// stated fact with a reason, not a gap the reader has to guess at.
|
|
70
|
+
for (const row of rows) {
|
|
71
|
+
if (row.ownerReason === null)
|
|
72
|
+
continue;
|
|
73
|
+
lines.push(`_\`${row.artifact}\` has no owning skill: ${row.ownerReason}_`);
|
|
74
|
+
lines.push('');
|
|
75
|
+
}
|
|
76
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/report-formatter-near-miss.ts`
|
|
3
|
+
*
|
|
4
|
+
* The near-miss section of the markdown report.
|
|
5
|
+
*
|
|
6
|
+
* WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
|
|
7
|
+
* 300-line cap, and this section does not fit beside the rest of it. The
|
|
8
|
+
* split follows the precedent in this directory: the hotspot section lives
|
|
9
|
+
* in `report-formatter-hotspots.ts` for the same reason.
|
|
10
|
+
*
|
|
11
|
+
* WHY THE RATE NEVER APPEARS ALONE. The report is what leaves the terminal
|
|
12
|
+
* — it gets pasted into a PR description — so a number in it has to be read
|
|
13
|
+
* the way it was measured. The near-miss rate is measured over the reason
|
|
14
|
+
* classes the scope had events for, and a scope can hold events for ONE of
|
|
15
|
+
* the three classes: the `gate` emitter postdates every session in this
|
|
16
|
+
* repository's recorded history, so two of the three classes have no events
|
|
17
|
+
* at all there.
|
|
18
|
+
*
|
|
19
|
+
* A rate printed on its own is therefore ambiguous between "there were no
|
|
20
|
+
* near-misses" and "the classes that could have shown a near-miss were never
|
|
21
|
+
* observed" — and the second reading is an ABSENCE read as a RESULT, which
|
|
22
|
+
* is the exact failure this whole programme exists to close. So the rate line
|
|
23
|
+
* carries its coverage with it: how many of the reason classes the rate was
|
|
24
|
+
* measured over, and that the rest is an absence of data rather than a
|
|
25
|
+
* result. A reader who sees ONLY the rate line still cannot draw the wrong
|
|
26
|
+
* conclusion.
|
|
27
|
+
*
|
|
28
|
+
* WHY THE COVERAGE IS A TABLE. Each class's rate divides by the slices THAT
|
|
29
|
+
* CLASS REACHED, not by every passing slice, so the class's own population
|
|
30
|
+
* has to travel with its number. The table says, per class: whether the class
|
|
31
|
+
* was observable at all, how many events it had, how many slices it reached,
|
|
32
|
+
* how many it flagged, and the rate it supports — or `not measured`, which is
|
|
33
|
+
* what a class with no events gets instead of a zero. It also says how many
|
|
34
|
+
* slices said NOTHING about the class: those slices could not be judged on it,
|
|
35
|
+
* and they are the ones a skipped check would hide in.
|
|
36
|
+
*
|
|
37
|
+
* WHY THE FLAGGED SLICES ARE LISTED. The count has to have a referent: a
|
|
38
|
+
* reader who is told that one slice passed with a check unsatisfied has to
|
|
39
|
+
* be able to see WHICH slice and WHICH check.
|
|
40
|
+
*/
|
|
41
|
+
import type { NearMissReport } from './near-miss.js';
|
|
42
|
+
/**
|
|
43
|
+
* The markdown for the near-miss section, including its heading.
|
|
44
|
+
*
|
|
45
|
+
* The section is rendered ONLY when the caller supplies the measurement, so a
|
|
46
|
+
* caller that does not compute it gets exactly the report it got before.
|
|
47
|
+
*/
|
|
48
|
+
export declare function markdownNearMissSection(nearMiss: NearMissReport): string;
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/observability/report-formatter-near-miss.ts`
|
|
3
|
+
*
|
|
4
|
+
* The near-miss section of the markdown report.
|
|
5
|
+
*
|
|
6
|
+
* WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
|
|
7
|
+
* 300-line cap, and this section does not fit beside the rest of it. The
|
|
8
|
+
* split follows the precedent in this directory: the hotspot section lives
|
|
9
|
+
* in `report-formatter-hotspots.ts` for the same reason.
|
|
10
|
+
*
|
|
11
|
+
* WHY THE RATE NEVER APPEARS ALONE. The report is what leaves the terminal
|
|
12
|
+
* — it gets pasted into a PR description — so a number in it has to be read
|
|
13
|
+
* the way it was measured. The near-miss rate is measured over the reason
|
|
14
|
+
* classes the scope had events for, and a scope can hold events for ONE of
|
|
15
|
+
* the three classes: the `gate` emitter postdates every session in this
|
|
16
|
+
* repository's recorded history, so two of the three classes have no events
|
|
17
|
+
* at all there.
|
|
18
|
+
*
|
|
19
|
+
* A rate printed on its own is therefore ambiguous between "there were no
|
|
20
|
+
* near-misses" and "the classes that could have shown a near-miss were never
|
|
21
|
+
* observed" — and the second reading is an ABSENCE read as a RESULT, which
|
|
22
|
+
* is the exact failure this whole programme exists to close. So the rate line
|
|
23
|
+
* carries its coverage with it: how many of the reason classes the rate was
|
|
24
|
+
* measured over, and that the rest is an absence of data rather than a
|
|
25
|
+
* result. A reader who sees ONLY the rate line still cannot draw the wrong
|
|
26
|
+
* conclusion.
|
|
27
|
+
*
|
|
28
|
+
* WHY THE COVERAGE IS A TABLE. Each class's rate divides by the slices THAT
|
|
29
|
+
* CLASS REACHED, not by every passing slice, so the class's own population
|
|
30
|
+
* has to travel with its number. The table says, per class: whether the class
|
|
31
|
+
* was observable at all, how many events it had, how many slices it reached,
|
|
32
|
+
* how many it flagged, and the rate it supports — or `not measured`, which is
|
|
33
|
+
* what a class with no events gets instead of a zero. It also says how many
|
|
34
|
+
* slices said NOTHING about the class: those slices could not be judged on it,
|
|
35
|
+
* and they are the ones a skipped check would hide in.
|
|
36
|
+
*
|
|
37
|
+
* WHY THE FLAGGED SLICES ARE LISTED. The count has to have a referent: a
|
|
38
|
+
* reader who is told that one slice passed with a check unsatisfied has to
|
|
39
|
+
* be able to see WHICH slice and WHICH check.
|
|
40
|
+
*/
|
|
41
|
+
/** How many decimals the rate's fraction is rounded to. */
|
|
42
|
+
const RATE_DECIMALS = 3;
|
|
43
|
+
/** How many decimals the rate's percentage is rounded to. */
|
|
44
|
+
const PERCENT_DECIMALS = 1;
|
|
45
|
+
/** The rate as a fraction and as a percentage — the two readings of one number. */
|
|
46
|
+
function formatRate(rate) {
|
|
47
|
+
const fraction = Number(rate.toFixed(RATE_DECIMALS));
|
|
48
|
+
const percent = Number((rate * 100).toFixed(PERCENT_DECIMALS));
|
|
49
|
+
return `${fraction} (${percent}%)`;
|
|
50
|
+
}
|
|
51
|
+
/** A rate as a percentage alone — the coverage table's cell. */
|
|
52
|
+
function formatPercent(rate) {
|
|
53
|
+
return `${Number((rate * 100).toFixed(PERCENT_DECIMALS))}%`;
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* The line that states the rate AND what the rate was measured over.
|
|
57
|
+
*
|
|
58
|
+
* The qualifier is on the rate's own line, not on a line further down, so a
|
|
59
|
+
* reader who reads nothing else still cannot take a zero for a finding.
|
|
60
|
+
*/
|
|
61
|
+
function rateLine(nearMiss) {
|
|
62
|
+
const observableCount = nearMiss.coverage.filter((item) => item.observable).length;
|
|
63
|
+
const unobservedCount = nearMiss.unobservedClasses.length;
|
|
64
|
+
const coverage = unobservedCount === 0
|
|
65
|
+
? `measured over all ${nearMiss.coverage.length} reason classes, every one of which was ` +
|
|
66
|
+
'OBSERVABLE in this scope'
|
|
67
|
+
: `measured over the ${observableCount} of ${nearMiss.coverage.length} reason classes that ` +
|
|
68
|
+
`were OBSERVABLE in this scope; the other ${unobservedCount} class(es) had no events to ` +
|
|
69
|
+
'observe, so their share of the rate is an absence of data, not a result';
|
|
70
|
+
return (`- **rate**: ${formatRate(nearMiss.nearMissRate)} — ` +
|
|
71
|
+
`${nearMiss.nearMissSliceCount} of ${nearMiss.passedSliceCount} passed slice(s) were ` +
|
|
72
|
+
`near-misses. The rate is ${coverage}.`);
|
|
73
|
+
}
|
|
74
|
+
/** The line that states the denominator and the definition it counts by. */
|
|
75
|
+
function denominatorLine(nearMiss) {
|
|
76
|
+
const denominator = nearMiss.denominator;
|
|
77
|
+
return `- **denominator**: ${denominator.sliceCount} slice(s) — ${denominator.definition}`;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The line that reconciles the denominator with the status summary's count.
|
|
81
|
+
*
|
|
82
|
+
* "Passed" has two definitions in this repository and they do not count the
|
|
83
|
+
* same slices, so the difference is stated rather than smoothed over.
|
|
84
|
+
*/
|
|
85
|
+
function statusLine(nearMiss) {
|
|
86
|
+
const denominator = nearMiss.denominator;
|
|
87
|
+
if (denominator.difference === null) {
|
|
88
|
+
return (`- **status summary's success count**: ${denominator.statusSuccessCount} — the two ` +
|
|
89
|
+
'"passed" definitions agree over this scope.');
|
|
90
|
+
}
|
|
91
|
+
return (`- **status summary's success count**: ${denominator.statusSuccessCount} — the two ` +
|
|
92
|
+
'"passed" definitions do NOT count the same slices; the gap is stated below.');
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* The lines that say which gates the stream did not decide.
|
|
96
|
+
*
|
|
97
|
+
* The count covers TWO kinds, and the wording names both: a gate whose
|
|
98
|
+
* LIVENESS the stream did not decide (no usable phase), and a gate whose
|
|
99
|
+
* VERDICT the stream did not decide (an outcome or a gate id this build does
|
|
100
|
+
* not know). A count that said only "liveness" would misdescribe the two of
|
|
101
|
+
* the three kinds it carries.
|
|
102
|
+
*/
|
|
103
|
+
function undeterminedLines(nearMiss) {
|
|
104
|
+
const lines = [
|
|
105
|
+
`- **undetermined**: ${nearMiss.undetermined.length} gate(s) whose liveness or verdict the ` +
|
|
106
|
+
'recorded stream did not decide.'
|
|
107
|
+
];
|
|
108
|
+
for (const item of nearMiss.undetermined) {
|
|
109
|
+
lines.push(` - \`${item.sliceRid}\` / \`${item.gateId}\` — ${item.reason}`);
|
|
110
|
+
}
|
|
111
|
+
return lines;
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* The lines that say which slices could not be MEASURED at all.
|
|
115
|
+
*
|
|
116
|
+
* A slice whose `verdict-issued` attempt records a prereq verdict this build
|
|
117
|
+
* cannot read is neither a pass nor a non-pass, so it is in neither the
|
|
118
|
+
* numerator nor the denominator. It is listed here because a slice that
|
|
119
|
+
* vanishes from the accounting reads as "no passing slices" — an absence read
|
|
120
|
+
* as a result.
|
|
121
|
+
*/
|
|
122
|
+
function unmeasuredLines(nearMiss) {
|
|
123
|
+
const lines = [
|
|
124
|
+
`- **unmeasured**: ${nearMiss.unmeasured.length} slice(s) whose pass verdict could not be READ, ` +
|
|
125
|
+
'so they are in neither the numerator nor the denominator.'
|
|
126
|
+
];
|
|
127
|
+
for (const item of nearMiss.unmeasured) {
|
|
128
|
+
lines.push(` - \`${item.sliceRid}\` — ${item.reason}`);
|
|
129
|
+
}
|
|
130
|
+
return lines;
|
|
131
|
+
}
|
|
132
|
+
/** The coverage table: what each reason class could and could not be observed for. */
|
|
133
|
+
function coverageTable(coverage) {
|
|
134
|
+
const lines = [];
|
|
135
|
+
lines.push('### Coverage');
|
|
136
|
+
lines.push('');
|
|
137
|
+
lines.push("Each class's rate is over the slices that class REACHED — a class that saw five slices " +
|
|
138
|
+
'out of a hundred reports one in five, not one in a hundred. A class with no events was ' +
|
|
139
|
+
'NOT observed, so it has no rate. The slices that recorded NOTHING about the class could ' +
|
|
140
|
+
'not be judged on it at all, so their count is stated beside the rate, as is the count of ' +
|
|
141
|
+
'the slices whose verdict could not be READ at all — they are in neither the numerator ' +
|
|
142
|
+
'nor the denominator.');
|
|
143
|
+
lines.push('');
|
|
144
|
+
lines.push('| reason class | observable | events | slices observed | slices with no events | ' +
|
|
145
|
+
'slices unreadable | slices flagged | rate |');
|
|
146
|
+
lines.push('|---|---|---|---|---|---|---|---|');
|
|
147
|
+
for (const item of coverage) {
|
|
148
|
+
lines.push(`| ${item.reason} | ${item.observable ? 'yes' : 'no'} | ${item.scopeEventCount} | ` +
|
|
149
|
+
`${item.observedSliceCount} | ${item.unobservedSliceCount} | ${item.unreadableSliceCount} | ` +
|
|
150
|
+
`${item.nearMissSliceCount} | ` +
|
|
151
|
+
`${item.rate === null ? 'not measured' : formatPercent(item.rate)} |`);
|
|
152
|
+
}
|
|
153
|
+
lines.push('');
|
|
154
|
+
return lines.join('\n');
|
|
155
|
+
}
|
|
156
|
+
/** The line that names the classes the rate does not measure. */
|
|
157
|
+
function unobservedLine(nearMiss) {
|
|
158
|
+
const unobserved = nearMiss.unobservedClasses;
|
|
159
|
+
if (unobserved.length === 0) {
|
|
160
|
+
return '- **unobserved classes**: none — every reason class had events to observe in this scope.';
|
|
161
|
+
}
|
|
162
|
+
const names = unobserved.map((reason) => `\`${reason}\``).join(', ');
|
|
163
|
+
return (`- **unobserved classes**: ${names} — these classes had NO events in this scope, so the ` +
|
|
164
|
+
'rate above does not measure them. A zero over an unobserved class is an absence of data, ' +
|
|
165
|
+
'not a result.');
|
|
166
|
+
}
|
|
167
|
+
/**
|
|
168
|
+
* The table of the slices the metric flagged, so the count has a referent.
|
|
169
|
+
*
|
|
170
|
+
* WHY EACH KEY CARRIES ITS STATE AT THE PASS MOMENT. "The check was
|
|
171
|
+
* unsatisfied" covers two materially different findings, and a reader has to
|
|
172
|
+
* be able to tell them apart:
|
|
173
|
+
*
|
|
174
|
+
* - `refused` — the check WAS running at the pass moment and said no. The
|
|
175
|
+
* gate was live, it fired, and the slice passed anyway.
|
|
176
|
+
* - `unattempted` — the check had NOT been run at the pass moment. The
|
|
177
|
+
* role that owns it had not yet attempted its transition.
|
|
178
|
+
*
|
|
179
|
+
* On this repository's recorded history one of the twelve findings is the
|
|
180
|
+
* first and eleven are the second — and the second is the more alarming of
|
|
181
|
+
* the two, because it means the pass was declared before the owning role had
|
|
182
|
+
* even tried. A table that said only "unsatisfied" would hide which of the
|
|
183
|
+
* two a reader is looking at.
|
|
184
|
+
*/
|
|
185
|
+
function flaggedSlices(nearMiss) {
|
|
186
|
+
const lines = [];
|
|
187
|
+
lines.push('### Flagged slices');
|
|
188
|
+
lines.push('');
|
|
189
|
+
if (nearMiss.records.length === 0) {
|
|
190
|
+
lines.push('_No slice passed with a required check still unsatisfied._');
|
|
191
|
+
lines.push('');
|
|
192
|
+
return lines.join('\n');
|
|
193
|
+
}
|
|
194
|
+
lines.push('| slice | reasons | passed at | unsatisfied checks |');
|
|
195
|
+
lines.push('|---|---|---|---|');
|
|
196
|
+
for (const record of nearMiss.records) {
|
|
197
|
+
const checks = record.unsatisfiedKeys.length === 0
|
|
198
|
+
? '—'
|
|
199
|
+
: record.unsatisfiedKeys.map((entry) => `${entry.key} (${entry.state})`).join(', ');
|
|
200
|
+
lines.push(`| ${record.sliceRid} | ${record.reasons.join(', ')} | ${record.passMoment.ts} | ${checks} |`);
|
|
201
|
+
}
|
|
202
|
+
lines.push('');
|
|
203
|
+
lines.push('_`refused` — the check was running at the pass moment and said no. ' +
|
|
204
|
+
'`unattempted` — the check had not been run at the pass moment at all, so the owning ' +
|
|
205
|
+
'role had not yet attempted its transition._');
|
|
206
|
+
lines.push('');
|
|
207
|
+
return lines.join('\n');
|
|
208
|
+
}
|
|
209
|
+
/**
|
|
210
|
+
* The markdown for the near-miss section, including its heading.
|
|
211
|
+
*
|
|
212
|
+
* The section is rendered ONLY when the caller supplies the measurement, so a
|
|
213
|
+
* caller that does not compute it gets exactly the report it got before.
|
|
214
|
+
*/
|
|
215
|
+
export function markdownNearMissSection(nearMiss) {
|
|
216
|
+
const lines = [];
|
|
217
|
+
lines.push('## Near-misses');
|
|
218
|
+
lines.push('');
|
|
219
|
+
lines.push(rateLine(nearMiss));
|
|
220
|
+
lines.push(denominatorLine(nearMiss));
|
|
221
|
+
lines.push(statusLine(nearMiss));
|
|
222
|
+
lines.push(...undeterminedLines(nearMiss));
|
|
223
|
+
lines.push(...unmeasuredLines(nearMiss));
|
|
224
|
+
if (nearMiss.denominator.difference !== null) {
|
|
225
|
+
lines.push('');
|
|
226
|
+
lines.push(nearMiss.denominator.difference.note);
|
|
227
|
+
}
|
|
228
|
+
lines.push('');
|
|
229
|
+
lines.push(coverageTable(nearMiss.coverage));
|
|
230
|
+
lines.push(unobservedLine(nearMiss));
|
|
231
|
+
lines.push('');
|
|
232
|
+
lines.push(flaggedSlices(nearMiss));
|
|
233
|
+
return lines.join('\n');
|
|
234
|
+
}
|
|
@@ -6,13 +6,20 @@
|
|
|
6
6
|
* entries. The CLI subcommand `peaks observability report` wires
|
|
7
7
|
* the file read + aggregation + format pipeline.
|
|
8
8
|
*
|
|
9
|
-
* - Header: scope, period, generated-at timestamp
|
|
10
|
-
*
|
|
9
|
+
* - Header: scope, period, generated-at timestamp, and any warning the
|
|
10
|
+
* scope or the period raised — the warning travels IN the body, because
|
|
11
|
+
* the body is what gets pasted and the stderr line is what gets lost
|
|
12
|
+
* - Near-miss section: rate | denominator | coverage | flagged slices
|
|
13
|
+
* - Slice table: rid | transitions | final state | duration | outcome
|
|
14
|
+
* - Hotspots table: artifact | owner | mode | confidence | count
|
|
11
15
|
* - Fanout table: role | count
|
|
12
16
|
* - Repair-cycle table: sliceRid | cycleCount
|
|
13
|
-
* - Top-N slowest slices:
|
|
17
|
+
* - Top-N slowest slices: rid | duration | transitions | final state,
|
|
18
|
+
* sorted by duration desc
|
|
14
19
|
*/
|
|
15
20
|
import { type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation.js';
|
|
21
|
+
import type { HotspotRow } from './hotspot-shared.js';
|
|
22
|
+
import type { NearMissReport } from './near-miss.js';
|
|
16
23
|
export type ReportInput = {
|
|
17
24
|
scope: 'session' | 'all-sessions';
|
|
18
25
|
scopeId: string;
|
|
@@ -22,6 +29,45 @@ export type ReportInput = {
|
|
|
22
29
|
slices: SliceRollup[];
|
|
23
30
|
fanout: FanoutBreakdown;
|
|
24
31
|
repairCycles: RepairCycleReport;
|
|
32
|
+
/**
|
|
33
|
+
* The warnings the scope or the period raised, rendered in the header.
|
|
34
|
+
*
|
|
35
|
+
* They are the reader's answer to "why is this table empty?" — a report
|
|
36
|
+
* scoped to one session, or narrowed to a period that holds no events,
|
|
37
|
+
* would otherwise show an empty table with no explanation. Printed to
|
|
38
|
+
* stderr they are lost the moment the report is pasted somewhere else, so
|
|
39
|
+
* the body carries them.
|
|
40
|
+
*/
|
|
41
|
+
warnings?: readonly string[];
|
|
42
|
+
/**
|
|
43
|
+
* The near-miss measurement, rendered when it is supplied.
|
|
44
|
+
*
|
|
45
|
+
* It is OPTIONAL, and absent means the section is not rendered at all — a
|
|
46
|
+
* caller that does not compute the measurement gets exactly the report it
|
|
47
|
+
* got before the section existed.
|
|
48
|
+
*
|
|
49
|
+
* THE SECTION NEVER PRINTS A BARE RATE. A rate over a reason class the
|
|
50
|
+
* scope had no events for is an absence of data, not a result, so the
|
|
51
|
+
* section carries the per-class coverage beside the number: which classes
|
|
52
|
+
* were observable, which were not, and that the unobserved ones are not
|
|
53
|
+
* measured. The section lives in `report-formatter-near-miss.ts` — this
|
|
54
|
+
* file was near its cap — and the reasoning is explained there.
|
|
55
|
+
*/
|
|
56
|
+
nearMiss?: NearMissReport;
|
|
57
|
+
/**
|
|
58
|
+
* The hotspot ranking, rendered when it is supplied.
|
|
59
|
+
*
|
|
60
|
+
* It is OPTIONAL, and absent means the section is not rendered at all — a
|
|
61
|
+
* caller that does not compute the ranking gets exactly the report it got
|
|
62
|
+
* before the ranking existed.
|
|
63
|
+
*
|
|
64
|
+
* THE SHAPE IS SET HERE, THE WIRING IS TASK 7's. The count column is
|
|
65
|
+
* named for what it counts — "times observed missing" and "candidate
|
|
66
|
+
* mentions" — so a reader cannot take a candidate mention for a missing
|
|
67
|
+
* artifact. The CLI command that supplies the ranking is Task 7's to
|
|
68
|
+
* wire; this file states the contract it will fill.
|
|
69
|
+
*/
|
|
70
|
+
hotspots?: readonly HotspotRow[];
|
|
25
71
|
};
|
|
26
72
|
declare function pad(value: string | number, width: number): string;
|
|
27
73
|
declare function formatDurationMs(ms: number | null): string;
|
|
@@ -6,13 +6,20 @@
|
|
|
6
6
|
* entries. The CLI subcommand `peaks observability report` wires
|
|
7
7
|
* the file read + aggregation + format pipeline.
|
|
8
8
|
*
|
|
9
|
-
* - Header: scope, period, generated-at timestamp
|
|
10
|
-
*
|
|
9
|
+
* - Header: scope, period, generated-at timestamp, and any warning the
|
|
10
|
+
* scope or the period raised — the warning travels IN the body, because
|
|
11
|
+
* the body is what gets pasted and the stderr line is what gets lost
|
|
12
|
+
* - Near-miss section: rate | denominator | coverage | flagged slices
|
|
13
|
+
* - Slice table: rid | transitions | final state | duration | outcome
|
|
14
|
+
* - Hotspots table: artifact | owner | mode | confidence | count
|
|
11
15
|
* - Fanout table: role | count
|
|
12
16
|
* - Repair-cycle table: sliceRid | cycleCount
|
|
13
|
-
* - Top-N slowest slices:
|
|
17
|
+
* - Top-N slowest slices: rid | duration | transitions | final state,
|
|
18
|
+
* sorted by duration desc
|
|
14
19
|
*/
|
|
15
|
-
import { REPAIR_CYCLE_METRIC_VERSION } from './aggregation.js';
|
|
20
|
+
import { REPAIR_CYCLE_METRIC_VERSION, sliceOutcome } from './aggregation.js';
|
|
21
|
+
import { markdownHotspotTables } from './report-formatter-hotspots.js';
|
|
22
|
+
import { markdownNearMissSection } from './report-formatter-near-miss.js';
|
|
16
23
|
const SLOWEST_TOP_N = 5;
|
|
17
24
|
function pad(value, width) {
|
|
18
25
|
const str = String(value);
|
|
@@ -35,6 +42,12 @@ function markdownHeader(input) {
|
|
|
35
42
|
lines.push(`- **period**: ${input.period}`);
|
|
36
43
|
lines.push(`- **generated at**: ${input.generatedAt}`);
|
|
37
44
|
lines.push(`- **scope marker**: from v2.11.1 install date (no backfill per PRD Q5)`);
|
|
45
|
+
const warnings = input.warnings ?? [];
|
|
46
|
+
if (warnings.length > 0) {
|
|
47
|
+
lines.push('');
|
|
48
|
+
for (const warning of warnings)
|
|
49
|
+
lines.push(`> **warning**: ${warning}`);
|
|
50
|
+
}
|
|
38
51
|
lines.push('');
|
|
39
52
|
return lines.join('\n');
|
|
40
53
|
}
|
|
@@ -48,11 +61,26 @@ function markdownStatusSummary(status) {
|
|
|
48
61
|
lines.push(`| total slices | ${status.totalSlices} |`);
|
|
49
62
|
lines.push(`| success count | ${status.successCount} |`);
|
|
50
63
|
lines.push(`| fail count | ${status.failCount} |`);
|
|
64
|
+
lines.push(`| stalled count | ${status.stalledCount} |`);
|
|
51
65
|
lines.push(`| repair-cycle peak (v${REPAIR_CYCLE_METRIC_VERSION} metric) | ${status.repairCyclePeak} |`);
|
|
52
66
|
lines.push(`| fanout cost total | ${status.fanoutCostTotal} |`);
|
|
53
67
|
lines.push('');
|
|
54
68
|
return lines.join('\n');
|
|
55
69
|
}
|
|
70
|
+
/**
|
|
71
|
+
* The marker each outcome is drawn with in the slice table.
|
|
72
|
+
*
|
|
73
|
+
* A stalled slice is NOT a failure: it advanced partway and stopped, and
|
|
74
|
+
* drawing it `✗` is what put the "8 failures" into a report whose own summary
|
|
75
|
+
* counted 0 — the two halves of one report disagreeing about the same slices.
|
|
76
|
+
* `…` says "did not finish" and leaves the failure marker for the slices that
|
|
77
|
+
* really were blocked.
|
|
78
|
+
*/
|
|
79
|
+
const OUTCOME_MARKERS = {
|
|
80
|
+
success: '✓',
|
|
81
|
+
failed: '✗',
|
|
82
|
+
stalled: '…'
|
|
83
|
+
};
|
|
56
84
|
function markdownSliceTable(slices) {
|
|
57
85
|
const lines = [];
|
|
58
86
|
lines.push('## Slices');
|
|
@@ -62,14 +90,22 @@ function markdownSliceTable(slices) {
|
|
|
62
90
|
lines.push('');
|
|
63
91
|
return lines.join('\n');
|
|
64
92
|
}
|
|
65
|
-
lines.push('| rid | transitions | final state | duration |
|
|
93
|
+
lines.push('| rid | transitions | final state | duration | outcome |');
|
|
66
94
|
lines.push('|---|---|---|---|---|');
|
|
67
95
|
for (const slice of slices) {
|
|
68
|
-
lines.push(`| ${slice.sliceRid} | ${slice.transitions} | ${slice.finalState ?? '—'} | ${formatDurationMs(slice.durationMs)} | ${slice
|
|
96
|
+
lines.push(`| ${slice.sliceRid} | ${slice.transitions} | ${slice.finalState ?? '—'} | ${formatDurationMs(slice.durationMs)} | ${OUTCOME_MARKERS[sliceOutcome(slice)]} |`);
|
|
69
97
|
}
|
|
70
98
|
lines.push('');
|
|
99
|
+
lines.push('_✓ succeeded · ✗ failed · … did not finish (stalled)_');
|
|
100
|
+
lines.push('');
|
|
71
101
|
return lines.join('\n');
|
|
72
102
|
}
|
|
103
|
+
/**
|
|
104
|
+
* The hotspot section: the rows, split by what their count actually counts.
|
|
105
|
+
*
|
|
106
|
+
* The section lives in `report-formatter-hotspots.ts` — this file was near
|
|
107
|
+
* its cap — and the split of the tables is explained there.
|
|
108
|
+
*/
|
|
73
109
|
function markdownFanoutTable(fanout) {
|
|
74
110
|
const lines = [];
|
|
75
111
|
lines.push('## Fanout');
|
|
@@ -148,14 +184,19 @@ function markdownSlowestSlices(slices) {
|
|
|
148
184
|
* layer reads events, calls aggregations, and passes the result here.
|
|
149
185
|
*/
|
|
150
186
|
export function renderObservabilityReport(input) {
|
|
151
|
-
const sections = [
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
187
|
+
const sections = [markdownHeader(input), markdownStatusSummary(input.status)];
|
|
188
|
+
// The near-miss section is rendered ONLY when the measurement is supplied,
|
|
189
|
+
// so a caller that does not compute it gets exactly the report it got
|
|
190
|
+
// before. It sits between the summary and the slice table: the summary
|
|
191
|
+
// says what the slices did, the near-misses say what was skipped.
|
|
192
|
+
if (input.nearMiss !== undefined)
|
|
193
|
+
sections.push(markdownNearMissSection(input.nearMiss));
|
|
194
|
+
sections.push(markdownSliceTable(input.slices));
|
|
195
|
+
// The hotspot section is rendered ONLY when the ranking is supplied, so a
|
|
196
|
+
// caller that does not compute it gets exactly the report it got before.
|
|
197
|
+
if (input.hotspots !== undefined)
|
|
198
|
+
sections.push(markdownHotspotTables(input.hotspots));
|
|
199
|
+
sections.push(markdownFanoutTable(input.fanout), markdownRepairCycleTable(input.repairCycles), markdownSlowestSlices(input.slices));
|
|
159
200
|
return sections.join('\n').trimEnd() + '\n';
|
|
160
201
|
}
|
|
161
202
|
export const REPORT_FORMAT_CONSTANTS = {
|