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,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/cli/commands/observability-commands-near-miss.ts`
|
|
3
|
+
*
|
|
4
|
+
* `peaks observability near-miss` — the headline number of the whole
|
|
5
|
+
* programme: of the slices that passed, how many passed anyway after a gate
|
|
6
|
+
* that was live never got evaluated?
|
|
7
|
+
*
|
|
8
|
+
* WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
|
|
9
|
+
* That file is at its file-size cap and a later task needs room in it too,
|
|
10
|
+
* so each subcommand's registration lives in its own module and the parent
|
|
11
|
+
* gains one import and one call. The precedent is the sibling split of
|
|
12
|
+
* `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
|
|
13
|
+
*
|
|
14
|
+
* WHY THE SCOPE BEHAVES LIKE THE OTHER QUERIES. The scope resolution, the
|
|
15
|
+
* `--all-sessions` escape and the empty-scope warning are the shared ones in
|
|
16
|
+
* `observability-commands-queries.ts`, so this command measures the same
|
|
17
|
+
* population its siblings report and says so the same way when it is empty.
|
|
18
|
+
*/
|
|
19
|
+
import type { Command } from 'commander';
|
|
20
|
+
import { type ProgramIO } from '../cli-helpers.js';
|
|
21
|
+
import { type ObservabilityQueryOptions } from './observability-commands-queries.js';
|
|
22
|
+
/**
|
|
23
|
+
* `peaks observability near-miss` — print the near-miss rate and the list of
|
|
24
|
+
* slices it came from.
|
|
25
|
+
*/
|
|
26
|
+
export declare function runNearMiss(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
27
|
+
/** Register `peaks observability near-miss` under the observability command. */
|
|
28
|
+
export declare function registerNearMissCommand(observability: Command, io: ProgramIO): void;
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/cli/commands/observability-commands-near-miss.ts`
|
|
3
|
+
*
|
|
4
|
+
* `peaks observability near-miss` — the headline number of the whole
|
|
5
|
+
* programme: of the slices that passed, how many passed anyway after a gate
|
|
6
|
+
* that was live never got evaluated?
|
|
7
|
+
*
|
|
8
|
+
* WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
|
|
9
|
+
* That file is at its file-size cap and a later task needs room in it too,
|
|
10
|
+
* so each subcommand's registration lives in its own module and the parent
|
|
11
|
+
* gains one import and one call. The precedent is the sibling split of
|
|
12
|
+
* `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
|
|
13
|
+
*
|
|
14
|
+
* WHY THE SCOPE BEHAVES LIKE THE OTHER QUERIES. The scope resolution, the
|
|
15
|
+
* `--all-sessions` escape and the empty-scope warning are the shared ones in
|
|
16
|
+
* `observability-commands-queries.ts`, so this command measures the same
|
|
17
|
+
* population its siblings report and says so the same way when it is empty.
|
|
18
|
+
*/
|
|
19
|
+
import { fail, ok } from 'peaks-loop-shared/result';
|
|
20
|
+
import { computeNearMiss } from '../../services/observability/near-miss.js';
|
|
21
|
+
import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
|
|
22
|
+
import { hotspotRequestTypes } from './observability-commands-hotspots.js';
|
|
23
|
+
import { readScopedEvents, resolveProjectRoot, scopeOf, scopeWarnings } from './observability-commands-queries.js';
|
|
24
|
+
/**
|
|
25
|
+
* The warning that says a reason class had no events to observe.
|
|
26
|
+
*
|
|
27
|
+
* A class with no events cannot produce a finding, so its share of the rate
|
|
28
|
+
* is an ABSENCE OF DATA. Saying nothing would let a reader take the rate for
|
|
29
|
+
* "no near-misses" when the truth is "this class was never looked at" — the
|
|
30
|
+
* exact misreading the metric exists to prevent.
|
|
31
|
+
*/
|
|
32
|
+
function coverageWarnings(coverage) {
|
|
33
|
+
return coverage
|
|
34
|
+
.filter((item) => !item.observable)
|
|
35
|
+
.map((item) => `The \`${item.reason}\` class had NO events to observe in this scope ` +
|
|
36
|
+
`(${item.scopeEventCount} event(s)), so its share of the near-miss rate is an ` +
|
|
37
|
+
'absence of data, not a result — the rate does not measure that class.');
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* The warning that says the denominator differs from the status summary's.
|
|
41
|
+
*
|
|
42
|
+
* "Passed" has two definitions in this repository and they do not count the
|
|
43
|
+
* same slices. A reader who sees one number and assumes it is the other's
|
|
44
|
+
* would be wrong, so the difference is stated rather than smoothed over.
|
|
45
|
+
*/
|
|
46
|
+
function denominatorWarnings(denominator) {
|
|
47
|
+
if (denominator.difference === null)
|
|
48
|
+
return [];
|
|
49
|
+
return [denominator.difference.note];
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* The warning that says a slice could not be measured at all.
|
|
53
|
+
*
|
|
54
|
+
* A slice whose `verdict-issued` attempt records a prereq verdict this build
|
|
55
|
+
* cannot read is in neither the numerator nor the denominator, so a reader who
|
|
56
|
+
* adds up the slices finds one missing. Saying nothing would let them infer
|
|
57
|
+
* it was never there.
|
|
58
|
+
*/
|
|
59
|
+
function unmeasuredWarnings(unmeasured) {
|
|
60
|
+
if (unmeasured.length === 0)
|
|
61
|
+
return [];
|
|
62
|
+
return [
|
|
63
|
+
`${unmeasured.length} slice(s) recorded a \`verdict-issued\` attempt whose prereq verdict this ` +
|
|
64
|
+
'build cannot read, so whether they passed is unknown — they are in neither the numerator ' +
|
|
65
|
+
`nor the denominator: ${unmeasured.map((item) => `\`${item.sliceRid}\``).join(', ')}`
|
|
66
|
+
];
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* `peaks observability near-miss` — print the near-miss rate and the list of
|
|
70
|
+
* slices it came from.
|
|
71
|
+
*/
|
|
72
|
+
export function runNearMiss(io, options) {
|
|
73
|
+
const projectRoot = resolveProjectRoot(options.project);
|
|
74
|
+
try {
|
|
75
|
+
const { sessionId, events } = readScopedEvents(projectRoot, options);
|
|
76
|
+
// The request types let the denominator NAME the cause of the gap between
|
|
77
|
+
// the two "passed" definitions: the slices that reached a verdict with no
|
|
78
|
+
// recorded prereq verdict are the ones whose type has no
|
|
79
|
+
// `qa:verdict-issued` prerequisite row at all.
|
|
80
|
+
const { requestTypes } = hotspotRequestTypes(projectRoot, events);
|
|
81
|
+
const report = computeNearMiss(events, requestTypes);
|
|
82
|
+
const warnings = [
|
|
83
|
+
...scopeWarnings(projectRoot, sessionId, events.length),
|
|
84
|
+
...coverageWarnings(report.coverage),
|
|
85
|
+
...denominatorWarnings(report.denominator),
|
|
86
|
+
...unmeasuredWarnings(report.unmeasured)
|
|
87
|
+
];
|
|
88
|
+
printResult(io, ok('observability.near-miss', { scope: scopeOf(sessionId), ...report }, warnings), options.json);
|
|
89
|
+
}
|
|
90
|
+
catch (error) {
|
|
91
|
+
printResult(io, fail('observability.near-miss', 'OBSERVABILITY_NEAR_MISS_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
|
|
92
|
+
process.exitCode = 1;
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
/** Register `peaks observability near-miss` under the observability command. */
|
|
96
|
+
export function registerNearMissCommand(observability, io) {
|
|
97
|
+
addJsonOption(observability
|
|
98
|
+
.command('near-miss')
|
|
99
|
+
.description('Near-miss rate: of the slices that were DECLARED PASSING (a `verdict-issued` attempt whose prereq check succeeded), how many passed anyway after a required check was still unsatisfied at that moment, or after a live gate never got evaluated? The `denominator` field states the definition and size of the population the rate divides by, and reconciles it with the status summary\'s success count — the two "passed" definitions do not count the same slices, and the difference is reported rather than smoothed over. The `coverage` field says, per reason class, whether that class had any events to observe: a class with none was not measured, so its share of the rate is an absence of data rather than a result.')
|
|
100
|
+
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
101
|
+
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
102
|
+
.option('--all-sessions', 'measure the whole recorded history of the project instead of the canonical session binding')).action((options) => {
|
|
103
|
+
runNearMiss(io, options);
|
|
104
|
+
});
|
|
105
|
+
}
|
|
@@ -15,28 +15,71 @@
|
|
|
15
15
|
* LATER ADDITION — `peaks observability repair-cycles` also grew an
|
|
16
16
|
* `--all-sessions` scope, so the whole recorded history of a project can be
|
|
17
17
|
* measured from the command itself.
|
|
18
|
+
*
|
|
19
|
+
* TASK 4 — the same `--all-sessions` scope now reaches `status` / `slices` /
|
|
20
|
+
* `fanout` / `report`, and every scoped query says so when its scope holds no
|
|
21
|
+
* events while OTHER sessions hold some.
|
|
18
22
|
*/
|
|
23
|
+
import { readAllSessionEvents } from '../../services/observability/aggregation.js';
|
|
19
24
|
import { type ProgramIO } from '../cli-helpers.js';
|
|
20
25
|
export declare function resolveProjectRoot(optionProject: string | undefined): string;
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
session?: string;
|
|
30
|
-
json?: boolean;
|
|
31
|
-
}): void;
|
|
32
|
-
export declare function runFanout(io: ProgramIO, options: {
|
|
33
|
-
project?: string;
|
|
34
|
-
session?: string;
|
|
35
|
-
json?: boolean;
|
|
36
|
-
}): void;
|
|
37
|
-
export declare function runRepairCycles(io: ProgramIO, options: {
|
|
26
|
+
/**
|
|
27
|
+
* The options every read-only observability query accepts.
|
|
28
|
+
*
|
|
29
|
+
* `allSessions` widens the scope from the canonical session binding to the
|
|
30
|
+
* WHOLE recorded history of the project — the same flag, and the same
|
|
31
|
+
* meaning, that `repair-cycles` already carries.
|
|
32
|
+
*/
|
|
33
|
+
export type ObservabilityQueryOptions = {
|
|
38
34
|
project?: string;
|
|
39
35
|
session?: string;
|
|
40
36
|
json?: boolean;
|
|
41
37
|
allSessions?: boolean;
|
|
42
|
-
}
|
|
38
|
+
};
|
|
39
|
+
/**
|
|
40
|
+
* The session a query reads, or `undefined` for EVERY session.
|
|
41
|
+
*
|
|
42
|
+
* `allSessions` short-circuits the resolution: the whole recorded history is
|
|
43
|
+
* read instead of the canonical session binding, and an explicit `--session`
|
|
44
|
+
* does not narrow it back. That is the precedence `repair-cycles
|
|
45
|
+
* --all-sessions` already has.
|
|
46
|
+
*/
|
|
47
|
+
export declare function resolveSessionId(optionSession: string | undefined, projectRoot: string, allSessions: boolean): string | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* The warnings a scoped query carries.
|
|
50
|
+
*
|
|
51
|
+
* A scoped query that reads zero events reads exactly like a project that
|
|
52
|
+
* recorded nothing, and the reader concludes the second — the events that ARE
|
|
53
|
+
* there stay invisible. So when the scope is empty while OTHER sessions hold
|
|
54
|
+
* events, the warning says how many sessions hold them, how many events in
|
|
55
|
+
* total, and names the flag that reaches them.
|
|
56
|
+
*
|
|
57
|
+
* Empty otherwise: either the scope holds events, or the scope already
|
|
58
|
+
* covers every session.
|
|
59
|
+
*/
|
|
60
|
+
export declare function scopeWarnings(projectRoot: string, scopedSessionId: string | undefined, scopedEventCount: number): string[];
|
|
61
|
+
/** What a scoped query reads: the session it was scoped to, and its events. */
|
|
62
|
+
export type ScopedRead = {
|
|
63
|
+
readonly sessionId: string | undefined;
|
|
64
|
+
readonly events: ReturnType<typeof readAllSessionEvents>;
|
|
65
|
+
};
|
|
66
|
+
/**
|
|
67
|
+
* The events a scoped query answers for: the one session the scope names, or
|
|
68
|
+
* every session the project recorded.
|
|
69
|
+
*/
|
|
70
|
+
export declare function readScopedEvents(projectRoot: string, options: ObservabilityQueryOptions): ScopedRead;
|
|
71
|
+
/**
|
|
72
|
+
* The scope a query answered for: one session, or every session.
|
|
73
|
+
*
|
|
74
|
+
* ONE spelling of that shape, exported because the report command answers
|
|
75
|
+
* with it too: a scope written two ways is a scope that can drift.
|
|
76
|
+
*/
|
|
77
|
+
export declare function scopeOf(sessionId: string | undefined): {
|
|
78
|
+
sessionId: string;
|
|
79
|
+
} | {
|
|
80
|
+
allSessions: true;
|
|
81
|
+
};
|
|
82
|
+
export declare function runStatus(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
83
|
+
export declare function runSlices(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
84
|
+
export declare function runFanout(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
85
|
+
export declare function runRepairCycles(io: ProgramIO, options: ObservabilityQueryOptions): void;
|
|
@@ -15,6 +15,10 @@
|
|
|
15
15
|
* LATER ADDITION — `peaks observability repair-cycles` also grew an
|
|
16
16
|
* `--all-sessions` scope, so the whole recorded history of a project can be
|
|
17
17
|
* measured from the command itself.
|
|
18
|
+
*
|
|
19
|
+
* TASK 4 — the same `--all-sessions` scope now reaches `status` / `slices` /
|
|
20
|
+
* `fanout` / `report`, and every scoped query says so when its scope holds no
|
|
21
|
+
* events while OTHER sessions hold some.
|
|
18
22
|
*/
|
|
19
23
|
import { fail, ok } from 'peaks-loop-shared/result';
|
|
20
24
|
import { findProjectRoot } from '../../services/config/config-safety.js';
|
|
@@ -27,28 +31,84 @@ export function resolveProjectRoot(optionProject) {
|
|
|
27
31
|
? resolveCanonicalProjectRoot(optionProject)
|
|
28
32
|
: (findProjectRoot(process.cwd()) ?? process.cwd());
|
|
29
33
|
}
|
|
30
|
-
|
|
34
|
+
/**
|
|
35
|
+
* The session a query reads, or `undefined` for EVERY session.
|
|
36
|
+
*
|
|
37
|
+
* `allSessions` short-circuits the resolution: the whole recorded history is
|
|
38
|
+
* read instead of the canonical session binding, and an explicit `--session`
|
|
39
|
+
* does not narrow it back. That is the precedence `repair-cycles
|
|
40
|
+
* --all-sessions` already has.
|
|
41
|
+
*/
|
|
42
|
+
export function resolveSessionId(optionSession, projectRoot, allSessions) {
|
|
43
|
+
if (allSessions)
|
|
44
|
+
return undefined;
|
|
31
45
|
if (optionSession !== undefined)
|
|
32
46
|
return optionSession;
|
|
33
47
|
return getSessionIdCanonical(projectRoot) ?? undefined;
|
|
34
48
|
}
|
|
49
|
+
/**
|
|
50
|
+
* The warnings a scoped query carries.
|
|
51
|
+
*
|
|
52
|
+
* A scoped query that reads zero events reads exactly like a project that
|
|
53
|
+
* recorded nothing, and the reader concludes the second — the events that ARE
|
|
54
|
+
* there stay invisible. So when the scope is empty while OTHER sessions hold
|
|
55
|
+
* events, the warning says how many sessions hold them, how many events in
|
|
56
|
+
* total, and names the flag that reaches them.
|
|
57
|
+
*
|
|
58
|
+
* Empty otherwise: either the scope holds events, or the scope already
|
|
59
|
+
* covers every session.
|
|
60
|
+
*/
|
|
61
|
+
export function scopeWarnings(projectRoot, scopedSessionId, scopedEventCount) {
|
|
62
|
+
if (scopedSessionId === undefined)
|
|
63
|
+
return [];
|
|
64
|
+
if (scopedEventCount > 0)
|
|
65
|
+
return [];
|
|
66
|
+
const sessions = new Set();
|
|
67
|
+
let eventCount = 0;
|
|
68
|
+
for (const event of readAllSessionEvents(projectRoot)) {
|
|
69
|
+
if (event.sessionId === scopedSessionId)
|
|
70
|
+
continue;
|
|
71
|
+
sessions.add(event.sessionId);
|
|
72
|
+
eventCount += 1;
|
|
73
|
+
}
|
|
74
|
+
if (eventCount === 0)
|
|
75
|
+
return [];
|
|
76
|
+
return [
|
|
77
|
+
`No observability events in session \`${scopedSessionId}\`; ` +
|
|
78
|
+
`${sessions.size} other session(s) hold ${eventCount} event(s) in total — ` +
|
|
79
|
+
'use `--all-sessions` to read them.'
|
|
80
|
+
];
|
|
81
|
+
}
|
|
82
|
+
/**
|
|
83
|
+
* The events a scoped query answers for: the one session the scope names, or
|
|
84
|
+
* every session the project recorded.
|
|
85
|
+
*/
|
|
86
|
+
export function readScopedEvents(projectRoot, options) {
|
|
87
|
+
const sessionId = resolveSessionId(options.session, projectRoot, options.allSessions === true);
|
|
88
|
+
const events = sessionId !== undefined
|
|
89
|
+
? readSessionEvents(projectRoot, sessionId)
|
|
90
|
+
: readAllSessionEvents(projectRoot);
|
|
91
|
+
return { sessionId, events };
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* The scope a query answered for: one session, or every session.
|
|
95
|
+
*
|
|
96
|
+
* ONE spelling of that shape, exported because the report command answers
|
|
97
|
+
* with it too: a scope written two ways is a scope that can drift.
|
|
98
|
+
*/
|
|
99
|
+
export function scopeOf(sessionId) {
|
|
100
|
+
return sessionId !== undefined ? { sessionId } : { allSessions: true };
|
|
101
|
+
}
|
|
35
102
|
export function runStatus(io, options) {
|
|
36
103
|
const projectRoot = resolveProjectRoot(options.project);
|
|
37
|
-
const sessionId = resolveSessionId(options.session, projectRoot);
|
|
38
104
|
try {
|
|
39
|
-
const events =
|
|
40
|
-
? readSessionEvents(projectRoot, sessionId)
|
|
41
|
-
: readAllSessionEvents(projectRoot);
|
|
105
|
+
const { sessionId, events } = readScopedEvents(projectRoot, options);
|
|
42
106
|
const status = aggregateStatus(events);
|
|
43
|
-
const warnings = sessionId
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
printResult(io, ok('observability.status', {
|
|
49
|
-
scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
|
|
50
|
-
status
|
|
51
|
-
}, warnings), options.json);
|
|
107
|
+
const warnings = scopeWarnings(projectRoot, sessionId, status.totalEvents);
|
|
108
|
+
if (sessionId === undefined && status.totalEvents === 0) {
|
|
109
|
+
warnings.push('No observability events found in any session — emit a slice transition via `peaks request transition` to populate.');
|
|
110
|
+
}
|
|
111
|
+
printResult(io, ok('observability.status', { scope: scopeOf(sessionId), status }, warnings), options.json);
|
|
52
112
|
}
|
|
53
113
|
catch (error) {
|
|
54
114
|
printResult(io, fail('observability.status', 'OBSERVABILITY_STATUS_FAILED', getErrorMessage(error), { projectRoot }, ['Run `peaks observability slices` for per-slice detail']), options.json);
|
|
@@ -57,17 +117,11 @@ export function runStatus(io, options) {
|
|
|
57
117
|
}
|
|
58
118
|
export function runSlices(io, options) {
|
|
59
119
|
const projectRoot = resolveProjectRoot(options.project);
|
|
60
|
-
const sessionId = resolveSessionId(options.session, projectRoot);
|
|
61
120
|
try {
|
|
62
|
-
const events =
|
|
63
|
-
? readSessionEvents(projectRoot, sessionId)
|
|
64
|
-
: readAllSessionEvents(projectRoot);
|
|
121
|
+
const { sessionId, events } = readScopedEvents(projectRoot, options);
|
|
65
122
|
const slices = aggregateSlices(events);
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
total: slices.length,
|
|
69
|
-
slices
|
|
70
|
-
}, []), options.json);
|
|
123
|
+
const warnings = scopeWarnings(projectRoot, sessionId, events.length);
|
|
124
|
+
printResult(io, ok('observability.slices', { scope: scopeOf(sessionId), total: slices.length, slices }, warnings), options.json);
|
|
71
125
|
}
|
|
72
126
|
catch (error) {
|
|
73
127
|
printResult(io, fail('observability.slices', 'OBSERVABILITY_SLICES_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
|
|
@@ -76,21 +130,14 @@ export function runSlices(io, options) {
|
|
|
76
130
|
}
|
|
77
131
|
export function runFanout(io, options) {
|
|
78
132
|
const projectRoot = resolveProjectRoot(options.project);
|
|
79
|
-
const sessionId = resolveSessionId(options.session, projectRoot);
|
|
80
133
|
try {
|
|
81
|
-
const events =
|
|
82
|
-
? readSessionEvents(projectRoot, sessionId)
|
|
83
|
-
: readAllSessionEvents(projectRoot);
|
|
134
|
+
const { sessionId, events } = readScopedEvents(projectRoot, options);
|
|
84
135
|
const fanout = aggregateFanout(events);
|
|
85
|
-
const warnings =
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
printResult(io, ok('observability.fanout', {
|
|
91
|
-
scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
|
|
92
|
-
fanout
|
|
93
|
-
}, warnings), options.json);
|
|
136
|
+
const warnings = scopeWarnings(projectRoot, sessionId, events.length);
|
|
137
|
+
if (fanout.total === 0) {
|
|
138
|
+
warnings.push('No dispatch events recorded in this scope — the fanout breakdown counts the dispatch events of the scope that was read.');
|
|
139
|
+
}
|
|
140
|
+
printResult(io, ok('observability.fanout', { scope: scopeOf(sessionId), fanout }, warnings), options.json);
|
|
94
141
|
}
|
|
95
142
|
catch (error) {
|
|
96
143
|
printResult(io, fail('observability.fanout', 'OBSERVABILITY_FANOUT_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
|
|
@@ -99,19 +146,13 @@ export function runFanout(io, options) {
|
|
|
99
146
|
}
|
|
100
147
|
export function runRepairCycles(io, options) {
|
|
101
148
|
const projectRoot = resolveProjectRoot(options.project);
|
|
102
|
-
// `--all-sessions` is the escape from the canonical-session binding: the
|
|
103
|
-
// recorded history (every session in the project) is the population the
|
|
104
|
-
// results baseline and the metric comparison are measured over.
|
|
105
|
-
const sessionId = options.allSessions === true ? undefined : resolveSessionId(options.session, projectRoot);
|
|
106
149
|
try {
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
150
|
+
// `--all-sessions` is the escape from the canonical-session binding: the
|
|
151
|
+
// recorded history (every session in the project) is the population the
|
|
152
|
+
// results baseline and the metric comparison are measured over.
|
|
153
|
+
const { sessionId, events } = readScopedEvents(projectRoot, options);
|
|
110
154
|
const cycles = aggregateRepairCycles(events);
|
|
111
|
-
printResult(io, ok('observability.repair-cycles', {
|
|
112
|
-
scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
|
|
113
|
-
cycles
|
|
114
|
-
}, []), options.json);
|
|
155
|
+
printResult(io, ok('observability.repair-cycles', { scope: scopeOf(sessionId), cycles }, scopeWarnings(projectRoot, sessionId, events.length)), options.json);
|
|
115
156
|
}
|
|
116
157
|
catch (error) {
|
|
117
158
|
printResult(io, fail('observability.repair-cycles', 'OBSERVABILITY_REPAIR_CYCLES_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
|
|
@@ -19,53 +19,107 @@
|
|
|
19
19
|
*/
|
|
20
20
|
import { fail, ok } from 'peaks-loop-shared/result';
|
|
21
21
|
import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
|
|
22
|
-
import { aggregateFanout, aggregateRepairCycles, aggregateSlices, aggregateStatus, filterByPeriod, periodStartIso
|
|
22
|
+
import { aggregateFanout, aggregateRepairCycles, aggregateSlices, aggregateStatus, filterByPeriod, periodStartIso } from '../../services/observability/aggregation.js';
|
|
23
23
|
import { renderObservabilityReport } from '../../services/observability/report-formatter.js';
|
|
24
|
+
import { computeNearMiss } from '../../services/observability/near-miss.js';
|
|
25
|
+
import { aggregateHotspots } from '../../services/observability/hotspots.js';
|
|
24
26
|
// Slice `b1-filesplit-campaign` (wave 3B): the four read-only query runners
|
|
25
27
|
// (`runStatus` / `runSlices` / `runFanout` / `runRepairCycles`) plus the two
|
|
26
28
|
// scope resolvers they share moved VERBATIM to `./observability-commands-queries.ts`
|
|
27
29
|
// so this file clears the 300 raw-line cap. What they do is unchanged;
|
|
28
30
|
// `runReport` — the one function here carrying a finding — stayed behind, so no
|
|
29
31
|
// finding moved into the new module.
|
|
30
|
-
import {
|
|
32
|
+
import { readScopedEvents, resolveProjectRoot, runFanout, runRepairCycles, runSlices, runStatus, scopeOf, scopeWarnings } from './observability-commands-queries.js';
|
|
31
33
|
import { runBaseline } from './observability-commands-baseline.js';
|
|
34
|
+
import { registerNearMissCommand } from './observability-commands-near-miss.js';
|
|
35
|
+
import { hotspotRequestTypes, registerHotspotsCommand } from './observability-commands-hotspots.js';
|
|
32
36
|
const VALID_PERIODS = ['day', 'week', 'month'];
|
|
37
|
+
/** The `--all-sessions` help text, ONE string for every command that carries it. */
|
|
38
|
+
const ALL_SESSIONS_DESCRIPTION = 'measure the whole recorded history of the project instead of the canonical session binding';
|
|
39
|
+
/**
|
|
40
|
+
* The warning a report carries when its PERIOD emptied the result.
|
|
41
|
+
*
|
|
42
|
+
* The scope and the period are two different axes: `--all-sessions` widens
|
|
43
|
+
* WHICH sessions are read, `--period` narrows WHICH DAYS of them count. A
|
|
44
|
+
* reader who scoped correctly and still saw an empty table was narrowed by
|
|
45
|
+
* the period, so the warning says the scope holds events and names the
|
|
46
|
+
* period window that reaches the most of them.
|
|
47
|
+
*/
|
|
48
|
+
function periodWarnings(scopedEvents, period, now) {
|
|
49
|
+
if (scopedEvents.length === 0)
|
|
50
|
+
return [];
|
|
51
|
+
if (filterByPeriod(scopedEvents, period, now).length > 0)
|
|
52
|
+
return [];
|
|
53
|
+
let reaching;
|
|
54
|
+
let reachingCount = 0;
|
|
55
|
+
for (const candidate of VALID_PERIODS) {
|
|
56
|
+
const count = filterByPeriod(scopedEvents, candidate, now).length;
|
|
57
|
+
if (count > 0 && count >= reachingCount) {
|
|
58
|
+
reaching = candidate;
|
|
59
|
+
reachingCount = count;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
if (reaching === undefined) {
|
|
63
|
+
return [
|
|
64
|
+
`No observability events fall inside the \`${period}\` period, and the scope's ` +
|
|
65
|
+
`${scopedEvents.length} event(s) are older than every period window — ` +
|
|
66
|
+
'no `--period` value reaches them.'
|
|
67
|
+
];
|
|
68
|
+
}
|
|
69
|
+
return [
|
|
70
|
+
`No observability events fall inside the \`${period}\` period, though the scope holds ` +
|
|
71
|
+
`${scopedEvents.length} event(s) — use \`--period ${reaching}\` to read them.`
|
|
72
|
+
];
|
|
73
|
+
}
|
|
33
74
|
function runReport(io, options) {
|
|
34
75
|
const projectRoot = resolveProjectRoot(options.project);
|
|
35
|
-
const sessionId = resolveSessionId(options.session, projectRoot);
|
|
36
76
|
const period = options.period !== undefined && VALID_PERIODS.includes(options.period)
|
|
37
77
|
? options.period
|
|
38
78
|
: 'day';
|
|
39
79
|
try {
|
|
40
|
-
const allEvents =
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
const
|
|
44
|
-
const
|
|
80
|
+
const { sessionId, events: allEvents } = readScopedEvents(projectRoot, options);
|
|
81
|
+
// ONE clock for the whole report: the window the events are filtered by
|
|
82
|
+
// and the window the warning names must be the same one.
|
|
83
|
+
const at = new Date();
|
|
84
|
+
const now = () => new Date(at);
|
|
85
|
+
const periodStart = periodStartIso(period, now);
|
|
86
|
+
const events = filterByPeriod(allEvents, period, now);
|
|
87
|
+
// The two measurements the report leads with. The request types are
|
|
88
|
+
// resolved through the hotspots command's own lookup, so the ranking in
|
|
89
|
+
// the report and the ranking the `hotspots` command prints cannot drift.
|
|
90
|
+
const { requestTypes } = hotspotRequestTypes(projectRoot, events);
|
|
91
|
+
const warnings = [
|
|
92
|
+
...scopeWarnings(projectRoot, sessionId, allEvents.length),
|
|
93
|
+
...periodWarnings(allEvents, period, now)
|
|
94
|
+
];
|
|
45
95
|
const markdown = renderObservabilityReport({
|
|
46
96
|
scope: sessionId !== undefined ? 'session' : 'all-sessions',
|
|
47
97
|
scopeId: sessionId ?? 'all',
|
|
48
98
|
period,
|
|
49
|
-
generatedAt:
|
|
99
|
+
generatedAt: at.toISOString(),
|
|
50
100
|
status: aggregateStatus(events),
|
|
51
101
|
slices: aggregateSlices(events),
|
|
52
102
|
fanout: aggregateFanout(events),
|
|
53
|
-
repairCycles: aggregateRepairCycles(events)
|
|
103
|
+
repairCycles: aggregateRepairCycles(events),
|
|
104
|
+
nearMiss: computeNearMiss(events, requestTypes),
|
|
105
|
+
hotspots: aggregateHotspots(events, requestTypes),
|
|
106
|
+
warnings
|
|
54
107
|
});
|
|
55
108
|
if (options.json === true) {
|
|
56
109
|
// --json on report: emit a metadata envelope so callers can
|
|
57
110
|
// machine-parse the markdown body without losing the envelope
|
|
58
111
|
// contract.
|
|
59
112
|
printResult(io, ok('observability.report', {
|
|
60
|
-
scope: sessionId
|
|
113
|
+
scope: scopeOf(sessionId),
|
|
61
114
|
period,
|
|
62
115
|
periodStart,
|
|
63
116
|
totalEventsScanned: allEvents.length,
|
|
64
117
|
totalEventsInPeriod: events.length,
|
|
65
118
|
markdown
|
|
66
|
-
},
|
|
119
|
+
}, warnings), true);
|
|
67
120
|
return;
|
|
68
121
|
}
|
|
122
|
+
// The warnings are IN the markdown header: the body is what gets pasted.
|
|
69
123
|
io.stdout(markdown);
|
|
70
124
|
}
|
|
71
125
|
catch (error) {
|
|
@@ -79,23 +133,26 @@ export function registerObservabilityCommands(program, io) {
|
|
|
79
133
|
.description('Read-only slice topology observability queries (v2.11.1). Reads JSONL metrics from .peaks/_runtime/<sessionId>/metrics/slices.jsonl.');
|
|
80
134
|
addJsonOption(observability
|
|
81
135
|
.command('status')
|
|
82
|
-
.description('Aggregate metrics for the active session (or all sessions with --project + omitted --session). Includes totalEvents / totalSlices / successCount / failCount / repairCyclePeak / fanoutCostTotal.')
|
|
136
|
+
.description('Aggregate metrics for the active session (or all sessions with --project + omitted --session). Includes totalEvents / totalSlices / successCount / failCount / stalledCount / repairCyclePeak / fanoutCostTotal.')
|
|
83
137
|
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
84
|
-
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
138
|
+
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
139
|
+
.option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
|
|
85
140
|
runStatus(io, options);
|
|
86
141
|
});
|
|
87
142
|
addJsonOption(observability
|
|
88
143
|
.command('slices')
|
|
89
144
|
.description('List all slices for the scope. Per slice: rid, transition count, first/last ts, durationMs, finalState, fanoutCount, repairCycleCount, success.')
|
|
90
145
|
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
91
|
-
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
146
|
+
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
147
|
+
.option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
|
|
92
148
|
runSlices(io, options);
|
|
93
149
|
});
|
|
94
150
|
addJsonOption(observability
|
|
95
151
|
.command('fanout')
|
|
96
152
|
.description('Fanout cost breakdown by sub-agent role (rd / qa / code-reviewer / karpathy-reviewer / peaks-security-audit / peaks-perf-audit; v2.12.0 collapse — `security-reviewer` removed from the role enum). Returns 0 per role until Slice C wires the `peaks sub-agent dispatch` hook.')
|
|
97
153
|
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
98
|
-
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
154
|
+
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
155
|
+
.option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
|
|
99
156
|
runFanout(io, options);
|
|
100
157
|
});
|
|
101
158
|
addJsonOption(observability
|
|
@@ -103,7 +160,7 @@ export function registerObservabilityCommands(program, io) {
|
|
|
103
160
|
.description('RD → QA repair-cycle count per slice (metric version 2: a repair cycle is a return to an RD work state after a QA phase). Cap = 3 (peaks-code repair-loop contract); capHit flag is set when any slice hits the cap. The version-1 qa-role event count is reported beside it as legacyQaEventCount — it is NOT a repair-cycle count.')
|
|
104
161
|
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
105
162
|
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
106
|
-
.option('--all-sessions',
|
|
163
|
+
.option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
|
|
107
164
|
runRepairCycles(io, options);
|
|
108
165
|
});
|
|
109
166
|
addJsonOption(observability
|
|
@@ -114,13 +171,15 @@ export function registerObservabilityCommands(program, io) {
|
|
|
114
171
|
.option('--check', 'compare the computed baseline against the tracked artifact and report drift')).action((options) => {
|
|
115
172
|
runBaseline(io, options);
|
|
116
173
|
});
|
|
117
|
-
observability
|
|
174
|
+
addJsonOption(observability
|
|
118
175
|
.command('report')
|
|
119
|
-
.description('Render a markdown summary suitable for paste into PR descriptions or .peaks/PROJECT.md timeline entries. Default period = day; --json emits an envelope wrapping the markdown body. Output sections: header + status summary + slice table + fanout table + repair-cycle table + top-N slowest slices.')
|
|
176
|
+
.description('Render a markdown summary suitable for paste into PR descriptions or .peaks/PROJECT.md timeline entries. Default period = day; --json emits an envelope wrapping the markdown body. Output sections: header + status summary + near-miss section (rate, denominator, per-class coverage, unobserved classes) + slice table + hotspot tables + fanout table + repair-cycle table + top-N slowest slices.')
|
|
120
177
|
.option('--project <path>', 'target project root (defaults to git root or cwd)')
|
|
121
178
|
.option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
|
|
122
179
|
.option('--period <period>', 'one of: day | week | month (defaults to day)', 'day')
|
|
123
|
-
.action((options) => {
|
|
180
|
+
.option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
|
|
124
181
|
runReport(io, options);
|
|
125
182
|
});
|
|
183
|
+
registerNearMissCommand(observability, io);
|
|
184
|
+
registerHotspotsCommand(observability, io);
|
|
126
185
|
}
|
|
@@ -84,6 +84,9 @@ export type PrerequisiteCheckResult = {
|
|
|
84
84
|
expiredWindow?: string;
|
|
85
85
|
}>;
|
|
86
86
|
};
|
|
87
|
+
type TransitionKey = `${RequestArtifactRole}:${RequestArtifactState}`;
|
|
88
|
+
type PrerequisiteTable = Partial<Record<TransitionKey, ReadonlyArray<ArtifactPrerequisite>>>;
|
|
89
|
+
export declare const PREREQUISITES_BY_TYPE: Record<RequestType, PrerequisiteTable>;
|
|
87
90
|
export type CheckPrerequisitesOptions = {
|
|
88
91
|
projectRoot: string;
|
|
89
92
|
/**
|
|
@@ -327,7 +327,7 @@ const CONFIG_TABLE = {
|
|
|
327
327
|
'rd:qa-handoff': [SECURITY_REVIEW],
|
|
328
328
|
'qa:verdict-issued': [TEST_REPORT]
|
|
329
329
|
};
|
|
330
|
-
const PREREQUISITES_BY_TYPE = {
|
|
330
|
+
export const PREREQUISITES_BY_TYPE = {
|
|
331
331
|
feature: FEATURE_TABLE,
|
|
332
332
|
bugfix: BUGFIX_TABLE,
|
|
333
333
|
refactor: REFACTOR_TABLE,
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `src/services/artifacts/prerequisite-path-census.ts`
|
|
3
|
+
*
|
|
4
|
+
* Every path shape that can reach the prerequisite missing list, as one
|
|
5
|
+
* de-duplicated list.
|
|
6
|
+
*
|
|
7
|
+
* WHY THIS EXISTS. The owner-skill map has to cover the paths the gates
|
|
8
|
+
* actually demand, and the gates read ONE table. Reading that table through
|
|
9
|
+
* a census function means the coverage check and the gate can never
|
|
10
|
+
* disagree about which paths exist — a second hand-written list would drift
|
|
11
|
+
* from the table on the first table change.
|
|
12
|
+
*
|
|
13
|
+
* THE THREE SOURCES OF A MISSING PATH. `checkPrerequisites` builds its
|
|
14
|
+
* missing list from three places, and a census that reads only the first
|
|
15
|
+
* would leave the other two uncovered:
|
|
16
|
+
*
|
|
17
|
+
* 1. the table loop — the canonical `relativePath`, plus the legacy tiers
|
|
18
|
+
* (`legacyRelativePath` / `legacyRelativePaths`) the resolver probes
|
|
19
|
+
* before it calls a file absent;
|
|
20
|
+
* 2. the judged-declaration refusals — the security artifact's own
|
|
21
|
+
* location, which the resolver reports verbatim;
|
|
22
|
+
* 3. the handoff capsule's gate-evidence declaration — a key that names a
|
|
23
|
+
* file that is not on disk, reported under the KEY's name, and the
|
|
24
|
+
* unreadable-capsule shape beside it.
|
|
25
|
+
*
|
|
26
|
+
* The `<rid>` placeholder is left in place on the table paths: this is the
|
|
27
|
+
* table's own shape, and the owner lookup is a prefix match, so the
|
|
28
|
+
* placeholder is irrelevant to it.
|
|
29
|
+
*
|
|
30
|
+
* THE KEY SET IS READ, NOT COPIED. `GATE_EVIDENCE_KEYS` is the one
|
|
31
|
+
* definition of the gate-evidence vocabulary, and a second copy of it here
|
|
32
|
+
* would be the same drift hole this census exists to close. The failure
|
|
33
|
+
* statuses are held in a `Record` keyed by the reader's own status type, so
|
|
34
|
+
* a status added to that type fails the build here until this census
|
|
35
|
+
* accounts for it.
|
|
36
|
+
*/
|
|
37
|
+
/**
|
|
38
|
+
* Every `relativePath` any request type demands, every legacy tier the
|
|
39
|
+
* resolver probes for one, and every gate-evidence shape a declaration can
|
|
40
|
+
* report — de-duplicated and sorted.
|
|
41
|
+
*/
|
|
42
|
+
export declare function allPrerequisitePaths(): readonly string[];
|