vouchington-tooling 0.66.1 → 0.67.0
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/README.md +42 -0
- package/dist/request-query-profile/baseline-validation.d.mts +2 -0
- package/dist/request-query-profile/baseline-validation.mjs +57 -0
- package/dist/request-query-profile/baseline.d.mts +49 -0
- package/dist/request-query-profile/baseline.mjs +66 -0
- package/dist/request-query-profile/index.d.mts +6 -0
- package/dist/request-query-profile/index.mjs +5 -0
- package/dist/request-query-profile/line.d.mts +21 -0
- package/dist/request-query-profile/line.mjs +48 -0
- package/dist/request-query-profile/observations.d.mts +13 -0
- package/dist/request-query-profile/observations.mjs +107 -0
- package/dist/request-query-profile/stale-report.d.mts +23 -0
- package/dist/request-query-profile/stale-report.mjs +52 -0
- package/dist/request-query-profile/types.d.mts +11 -0
- package/dist/request-query-profile/types.mjs +1 -0
- package/package.json +6 -1
- package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
package/README.md
CHANGED
|
@@ -1196,6 +1196,48 @@ touching it. `tmux post-tool` reads an agent post-tool hook payload on stdin and
|
|
|
1196
1196
|
reminder at plan, PR, push and reset checkpoints; reminders name `TMUX_NAME_COMMAND` (default
|
|
1197
1197
|
`vouchington tmux name`).
|
|
1198
1198
|
|
|
1199
|
+
## Request query profiles
|
|
1200
|
+
|
|
1201
|
+
`vouchington-tooling/request-query-profile` is the test-only rule layer on top of a per-request
|
|
1202
|
+
query telemetry summary. It has no runtime dependencies: the summary is a structural type
|
|
1203
|
+
(`{ totalQueries, serialDepth, repeats: { annotation, count }[] }`) and the route resolver is a
|
|
1204
|
+
function you pass in.
|
|
1205
|
+
|
|
1206
|
+
```ts
|
|
1207
|
+
import {
|
|
1208
|
+
buildStaleReport,
|
|
1209
|
+
findUnbaselinedRepeats,
|
|
1210
|
+
formatRequestProfileLine,
|
|
1211
|
+
formatUnbaselinedRepeats,
|
|
1212
|
+
parseRepeatBaseline,
|
|
1213
|
+
parseRequestProfileLine,
|
|
1214
|
+
} from 'vouchington-tooling/request-query-profile'
|
|
1215
|
+
|
|
1216
|
+
const baseline = parseRepeatBaseline(JSON.parse(baselineJson))
|
|
1217
|
+
const line = formatRequestProfileLine('GET /orders/:id', summary, { all: false }) // null if no repeats
|
|
1218
|
+
const parsed = parseRequestProfileLine(line ?? '') // { route, queries, serialDepth, repeats }
|
|
1219
|
+
const bad = findUnbaselinedRepeats('GET /orders/:id', summary.repeats, baseline)
|
|
1220
|
+
if (bad.length > 0)
|
|
1221
|
+
throw new Error(
|
|
1222
|
+
formatUnbaselinedRepeats('GET /orders/:id', bad, { baselineFile: 'test/query-baseline.json' }),
|
|
1223
|
+
)
|
|
1224
|
+
const report = buildStaleReport(baseline, [logText], (route) => route) // report-only
|
|
1225
|
+
```
|
|
1226
|
+
|
|
1227
|
+
- A baseline entry names an `annotation`, a `reason`, exact `routes` (`METHOD /path`, optionally
|
|
1228
|
+
followed by ` tools/call <name>`) and optional `workers: [{ queue, job }]`, a `maxCount` (an
|
|
1229
|
+
integer of at least 2, or `null` for unbounded), and either `issue` (a positive issue number, a
|
|
1230
|
+
temporary entry) or `permanent: true` with `code` (`<repo path>:<line, range or symbol>`).
|
|
1231
|
+
`parseRepeatBaseline` throws naming every malformed or duplicate-scope entry.
|
|
1232
|
+
- `formatClosedBaselineIssues(baseline, states, { issueGroup })` reports temporary entries whose
|
|
1233
|
+
issue is not open; `states` maps issue numbers to their GitHub state.
|
|
1234
|
+
- `formatRequestProfileLine` and `parseRequestProfileLine` are inverses and live in one module, so
|
|
1235
|
+
the line format cannot drift. `collectProfileObservations` also reads
|
|
1236
|
+
`{"kind":"pg-worker-profile", ...}` JSON lines, including nested `children`.
|
|
1237
|
+
- `buildStaleReport(baseline, logTexts, resolveRoute)` and `findStaleBaselineEntries` never treat a
|
|
1238
|
+
missing or malformed diagnostic kind as evidence of absence: `sufficient` is false then, and the
|
|
1239
|
+
scopes of that kind stay unreported.
|
|
1240
|
+
|
|
1199
1241
|
## PostgreSQL test faults and lock waits
|
|
1200
1242
|
|
|
1201
1243
|
`vouchington-tooling/postgres-test-faults` injects real PostgreSQL failures and observes real lock
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
const CODE_POINTER = /^[\w./-]+\.\w+:(?:[1-9]\d*(?:-[1-9]\d*)?|[A-Za-z_$][\w$.]*)$/;
|
|
2
|
+
const ROUTE = /^[A-Z]+ \/[^?\s]*(?: tools\/call [^?\s]+)?$/;
|
|
3
|
+
function rangeIsOrdered(code) {
|
|
4
|
+
const range = /:(\d+)-(\d+)$/.exec(code);
|
|
5
|
+
return range === null || Number(range[1]) <= Number(range[2]);
|
|
6
|
+
}
|
|
7
|
+
/** Validates the exact temporary or permanent metadata shape of one query-profile exception. */
|
|
8
|
+
export function baselineEntryProblem(entry) {
|
|
9
|
+
if (typeof entry !== 'object' || entry === null)
|
|
10
|
+
return 'is not an object';
|
|
11
|
+
const { annotation, reason, routes, workers, maxCount, ...rest } = entry;
|
|
12
|
+
if (typeof annotation !== 'string' || annotation.trim() === '')
|
|
13
|
+
return 'needs a non-empty annotation';
|
|
14
|
+
if (typeof reason !== 'string' || reason.trim() === '')
|
|
15
|
+
return 'needs a non-empty reason';
|
|
16
|
+
if (!Array.isArray(routes) ||
|
|
17
|
+
routes.some((route) => typeof route !== 'string' || !ROUTE.test(route)))
|
|
18
|
+
return 'needs `routes` as an array of exact method and path identities without queries';
|
|
19
|
+
if (workers !== undefined &&
|
|
20
|
+
(!Array.isArray(workers) ||
|
|
21
|
+
workers.some((worker) => {
|
|
22
|
+
if (typeof worker !== 'object' || worker === null)
|
|
23
|
+
return true;
|
|
24
|
+
const { queue, job, ...extra } = worker;
|
|
25
|
+
return (Object.keys(extra).length > 0 ||
|
|
26
|
+
typeof queue !== 'string' ||
|
|
27
|
+
queue.trim() === '' ||
|
|
28
|
+
queue.includes('*') ||
|
|
29
|
+
typeof job !== 'string' ||
|
|
30
|
+
job.trim() === '' ||
|
|
31
|
+
job.includes('*'));
|
|
32
|
+
})))
|
|
33
|
+
return 'needs `workers` as exact { queue, job } identities';
|
|
34
|
+
if (routes.length === 0 && (!workers || workers.length === 0))
|
|
35
|
+
return 'needs at least one route or worker identity';
|
|
36
|
+
if (maxCount !== null && (!Number.isInteger(maxCount) || maxCount < 2))
|
|
37
|
+
return 'needs `maxCount` as an integer at least 2, or null';
|
|
38
|
+
const keys = Object.keys(rest).toSorted().join(',');
|
|
39
|
+
if (keys === 'issue') {
|
|
40
|
+
const { issue } = rest;
|
|
41
|
+
if (typeof issue !== 'number' || !Number.isInteger(issue) || issue <= 0)
|
|
42
|
+
return 'needs `issue` to be a positive issue number';
|
|
43
|
+
return undefined;
|
|
44
|
+
}
|
|
45
|
+
if (keys === 'code,permanent') {
|
|
46
|
+
if (rest.permanent !== true)
|
|
47
|
+
return 'needs `permanent: true`';
|
|
48
|
+
if (typeof rest.code !== 'string' ||
|
|
49
|
+
!CODE_POINTER.test(rest.code) ||
|
|
50
|
+
rest.code.startsWith('/') ||
|
|
51
|
+
!rangeIsOrdered(rest.code) ||
|
|
52
|
+
rest.code.split(':')[0].split('/').includes('..'))
|
|
53
|
+
return 'needs `code` as "<repo path>:<line or symbol>"';
|
|
54
|
+
return undefined;
|
|
55
|
+
}
|
|
56
|
+
return 'must be temporary { annotation, reason, issue } or permanent { annotation, reason, permanent: true, code }';
|
|
57
|
+
}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import type { RepeatedAnnotation } from './types.mts';
|
|
2
|
+
/** A repeat tolerated until the open `issue` removes it. */
|
|
3
|
+
export interface BaselineScope {
|
|
4
|
+
/** Exact request identities, including MCP tool-call identities. */
|
|
5
|
+
routes: string[];
|
|
6
|
+
/** Exact worker identities. Worker scopes never excuse a request repeat. */
|
|
7
|
+
workers?: Array<{
|
|
8
|
+
queue: string;
|
|
9
|
+
job: string;
|
|
10
|
+
}>;
|
|
11
|
+
/** Null preserves an intentional unbounded exception within the named scopes. */
|
|
12
|
+
maxCount: number | null;
|
|
13
|
+
}
|
|
14
|
+
export interface TemporaryBaselineEntry extends BaselineScope {
|
|
15
|
+
annotation: string;
|
|
16
|
+
reason: string;
|
|
17
|
+
/** Number of the open GitHub issue that owns removing the repeat. */
|
|
18
|
+
issue: number;
|
|
19
|
+
}
|
|
20
|
+
/** A repeat the code needs on purpose; the reason names the mechanism. */
|
|
21
|
+
export interface PermanentBaselineEntry extends BaselineScope {
|
|
22
|
+
annotation: string;
|
|
23
|
+
reason: string;
|
|
24
|
+
permanent: true;
|
|
25
|
+
/** `<repo path>:<line or symbol>` of the code that needs the repeat. */
|
|
26
|
+
code: string;
|
|
27
|
+
}
|
|
28
|
+
export type RepeatBaselineEntry = TemporaryBaselineEntry | PermanentBaselineEntry;
|
|
29
|
+
/** Parsed baseline, or an error naming every malformed or duplicate entry. */
|
|
30
|
+
export declare function parseRepeatBaseline(raw: unknown): RepeatBaselineEntry[];
|
|
31
|
+
/** Temporary entries, whose `issue` must stay open. */
|
|
32
|
+
export declare function temporaryBaselineEntries(baseline: readonly RepeatBaselineEntry[]): TemporaryBaselineEntry[];
|
|
33
|
+
/** Repeats outside their exact baseline scope and maximum, in the order given. */
|
|
34
|
+
export declare function findUnbaselinedRepeats(route: string, repeats: readonly RepeatedAnnotation[], baseline: readonly RepeatBaselineEntry[]): RepeatedAnnotation[];
|
|
35
|
+
/**
|
|
36
|
+
* Failure text for one request: names the route and every unbaselined annotation.
|
|
37
|
+
* `baselineFile` is the repository path of the baseline, shown in the remediation hint.
|
|
38
|
+
*/
|
|
39
|
+
export declare function formatUnbaselinedRepeats(route: string, repeats: readonly RepeatedAnnotation[], options: {
|
|
40
|
+
baselineFile: string;
|
|
41
|
+
}): string;
|
|
42
|
+
/**
|
|
43
|
+
* Failure text for temporary entries whose issue is not open, one line per entry. `states` maps an
|
|
44
|
+
* issue number to its GitHub state; an issue missing from it counts as not found. `issueGroup`
|
|
45
|
+
* names where replacement issues live (for example a milestone or issue group title).
|
|
46
|
+
*/
|
|
47
|
+
export declare function formatClosedBaselineIssues(baseline: readonly RepeatBaselineEntry[], states: ReadonlyMap<number, string>, options: {
|
|
48
|
+
issueGroup: string;
|
|
49
|
+
}): string[];
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { baselineEntryProblem } from "./baseline-validation.mjs";
|
|
2
|
+
function entryScopes(scoped) {
|
|
3
|
+
return [
|
|
4
|
+
...scoped.routes.map((route) => JSON.stringify([scoped.annotation, 'route', route])),
|
|
5
|
+
...(scoped.workers ?? []).map(({ queue, job }) => JSON.stringify([scoped.annotation, 'worker', queue, job])),
|
|
6
|
+
];
|
|
7
|
+
}
|
|
8
|
+
/** Parsed baseline, or an error naming every malformed or duplicate entry. */
|
|
9
|
+
export function parseRepeatBaseline(raw) {
|
|
10
|
+
if (!Array.isArray(raw))
|
|
11
|
+
throw new Error('Query-profile baseline must be an array of entries');
|
|
12
|
+
const problems = [];
|
|
13
|
+
const seenScopes = new Set();
|
|
14
|
+
raw.forEach((entry, index) => {
|
|
15
|
+
const problem = baselineEntryProblem(entry);
|
|
16
|
+
const name = entry?.annotation;
|
|
17
|
+
if (problem)
|
|
18
|
+
problems.push(`entry ${index} (${JSON.stringify(name)}) ${problem}`);
|
|
19
|
+
else {
|
|
20
|
+
for (const scope of entryScopes(entry)) {
|
|
21
|
+
if (seenScopes.has(scope))
|
|
22
|
+
problems.push(`entry ${index} (${JSON.stringify(name)}) has a duplicate scope ${scope}`);
|
|
23
|
+
seenScopes.add(scope);
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
});
|
|
27
|
+
if (problems.length > 0) {
|
|
28
|
+
throw new Error(`Malformed query-profile baseline:\n${problems.join('\n')}`);
|
|
29
|
+
}
|
|
30
|
+
return raw;
|
|
31
|
+
}
|
|
32
|
+
/** Temporary entries, whose `issue` must stay open. */
|
|
33
|
+
export function temporaryBaselineEntries(baseline) {
|
|
34
|
+
return baseline.filter((entry) => 'issue' in entry);
|
|
35
|
+
}
|
|
36
|
+
/** Repeats outside their exact baseline scope and maximum, in the order given. */
|
|
37
|
+
export function findUnbaselinedRepeats(route, repeats, baseline) {
|
|
38
|
+
return repeats.filter(({ annotation, count }) => {
|
|
39
|
+
return !baseline.some((entry) => entry.annotation === annotation &&
|
|
40
|
+
entry.routes.includes(route) &&
|
|
41
|
+
(entry.maxCount === null || count <= entry.maxCount));
|
|
42
|
+
});
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Failure text for one request: names the route and every unbaselined annotation.
|
|
46
|
+
* `baselineFile` is the repository path of the baseline, shown in the remediation hint.
|
|
47
|
+
*/
|
|
48
|
+
export function formatUnbaselinedRepeats(route, repeats, options) {
|
|
49
|
+
const list = repeats.map(({ annotation, count }) => `${annotation} (x${count})`).join(', ');
|
|
50
|
+
return `Unbaselined repeated query in ${route}: ${list}. Remove the repeat, or baseline it in ${options.baselineFile} with a reason and an open issue (temporary), or a code pointer (permanent).`;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Failure text for temporary entries whose issue is not open, one line per entry. `states` maps an
|
|
54
|
+
* issue number to its GitHub state; an issue missing from it counts as not found. `issueGroup`
|
|
55
|
+
* names where replacement issues live (for example a milestone or issue group title).
|
|
56
|
+
*/
|
|
57
|
+
export function formatClosedBaselineIssues(baseline, states, options) {
|
|
58
|
+
return temporaryBaselineEntries(baseline).flatMap(({ annotation, issue }) => {
|
|
59
|
+
const state = states.get(issue)?.toLowerCase();
|
|
60
|
+
if (state === 'open')
|
|
61
|
+
return [];
|
|
62
|
+
return [
|
|
63
|
+
`Baseline entry ${annotation} points at #${issue}, which is ${state ?? 'not found'}. Remove the repeat, or re-point the entry at an open issue in "${options.issueGroup}"; a repeat the code needs on purpose becomes a permanent entry.`,
|
|
64
|
+
];
|
|
65
|
+
});
|
|
66
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export { findUnbaselinedRepeats, formatClosedBaselineIssues, formatUnbaselinedRepeats, parseRepeatBaseline, temporaryBaselineEntries, type BaselineScope, type PermanentBaselineEntry, type RepeatBaselineEntry, type TemporaryBaselineEntry, } from './baseline.mts';
|
|
2
|
+
export { baselineEntryProblem } from './baseline-validation.mts';
|
|
3
|
+
export { formatRequestProfileLine, parseRequestProfileLine, REQUEST_PROFILE_PREFIX, type ParsedRequestProfileLine, } from './line.mts';
|
|
4
|
+
export { collectProfileObservations, type ProfileObservations } from './observations.mts';
|
|
5
|
+
export { buildStaleReport, findStaleBaselineEntries, MIN_STALE_EVIDENCE_LOGS, type StaleBaselineCandidate, type StaleReport, } from './stale-report.mts';
|
|
6
|
+
export type { RepeatedAnnotation, RequestQuerySummary } from './types.mts';
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export { findUnbaselinedRepeats, formatClosedBaselineIssues, formatUnbaselinedRepeats, parseRepeatBaseline, temporaryBaselineEntries, } from "./baseline.mjs";
|
|
2
|
+
export { baselineEntryProblem } from "./baseline-validation.mjs";
|
|
3
|
+
export { formatRequestProfileLine, parseRequestProfileLine, REQUEST_PROFILE_PREFIX, } from "./line.mjs";
|
|
4
|
+
export { collectProfileObservations } from "./observations.mjs";
|
|
5
|
+
export { buildStaleReport, findStaleBaselineEntries, MIN_STALE_EVIDENCE_LOGS, } from "./stale-report.mjs";
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { RepeatedAnnotation, RequestQuerySummary } from './types.mts';
|
|
2
|
+
export declare const REQUEST_PROFILE_PREFIX = "[pg-request-profile]";
|
|
3
|
+
/** A parsed request profile line. */
|
|
4
|
+
export interface ParsedRequestProfileLine {
|
|
5
|
+
route: string;
|
|
6
|
+
queries: number;
|
|
7
|
+
serialDepth: number;
|
|
8
|
+
repeats: RepeatedAnnotation[];
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* One stderr line for a request, or null when it has nothing to report and `all` is off.
|
|
12
|
+
* Annotations are written verbatim, so one containing a comma does not survive parsing.
|
|
13
|
+
*/
|
|
14
|
+
export declare function formatRequestProfileLine(route: string, summary: RequestQuerySummary, options: {
|
|
15
|
+
all: boolean;
|
|
16
|
+
}): string | null;
|
|
17
|
+
/**
|
|
18
|
+
* Parse a line containing the profile prefix (leading log noise is skipped), or undefined when it
|
|
19
|
+
* is malformed. The inverse of `formatRequestProfileLine`.
|
|
20
|
+
*/
|
|
21
|
+
export declare function parseRequestProfileLine(line: string): ParsedRequestProfileLine | undefined;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
export const REQUEST_PROFILE_PREFIX = '[pg-request-profile]';
|
|
2
|
+
/**
|
|
3
|
+
* One stderr line for a request, or null when it has nothing to report and `all` is off.
|
|
4
|
+
* Annotations are written verbatim, so one containing a comma does not survive parsing.
|
|
5
|
+
*/
|
|
6
|
+
export function formatRequestProfileLine(route, summary, options) {
|
|
7
|
+
if (summary.repeats.length === 0 && !options.all)
|
|
8
|
+
return null;
|
|
9
|
+
const repeats = summary.repeats
|
|
10
|
+
.map(({ annotation, count }) => `${annotation}(x${count})`)
|
|
11
|
+
.join(',');
|
|
12
|
+
return `${REQUEST_PROFILE_PREFIX} route=${route} queries=${summary.totalQueries} serialDepth=${summary.serialDepth} repeats=${repeats || 'none'}\n`;
|
|
13
|
+
}
|
|
14
|
+
/** Parse the repeats field; undefined when any entry is malformed or counts fewer than 2. */
|
|
15
|
+
function parseRepeats(repeats) {
|
|
16
|
+
if (repeats === '' || repeats === 'none')
|
|
17
|
+
return [];
|
|
18
|
+
const parsed = [];
|
|
19
|
+
for (const value of repeats.split(',')) {
|
|
20
|
+
const match = /^(.+?)\(x(\d+)\)$/.exec(value);
|
|
21
|
+
if (!match?.[1]?.trim() || Number(match[2]) < 2)
|
|
22
|
+
return undefined;
|
|
23
|
+
parsed.push({ annotation: match[1], count: Number(match[2]) });
|
|
24
|
+
}
|
|
25
|
+
return parsed;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Parse a line containing the profile prefix (leading log noise is skipped), or undefined when it
|
|
29
|
+
* is malformed. The inverse of `formatRequestProfileLine`.
|
|
30
|
+
*/
|
|
31
|
+
export function parseRequestProfileLine(line) {
|
|
32
|
+
const start = line.indexOf(REQUEST_PROFILE_PREFIX);
|
|
33
|
+
if (start === -1)
|
|
34
|
+
return undefined;
|
|
35
|
+
const profile = line.slice(start).trimEnd();
|
|
36
|
+
const match = / route=(.+?) queries=(\d+) serialDepth=(\d+) repeats=(.*)$/.exec(profile);
|
|
37
|
+
const route = match?.[1];
|
|
38
|
+
const repeats = match?.[4];
|
|
39
|
+
const parsed = repeats === undefined ? undefined : parseRepeats(repeats);
|
|
40
|
+
if (!route || parsed === undefined)
|
|
41
|
+
return undefined;
|
|
42
|
+
return {
|
|
43
|
+
route,
|
|
44
|
+
queries: Number(match?.[2]),
|
|
45
|
+
serialDepth: Number(match?.[3]),
|
|
46
|
+
repeats: parsed,
|
|
47
|
+
};
|
|
48
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export interface ProfileObservations {
|
|
2
|
+
requestProfileCount: number;
|
|
3
|
+
workerProfileCount: number;
|
|
4
|
+
malformedRequestProfileCount: number;
|
|
5
|
+
malformedWorkerProfileCount: number;
|
|
6
|
+
routeScopes: Set<string>;
|
|
7
|
+
workerScopes: Set<string>;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Collect exact repeated-query scopes and valid request/worker diagnostics from run logs. Worker
|
|
11
|
+
* lines are recognized by the compact `"kind":"pg-worker-profile"` form `JSON.stringify` writes.
|
|
12
|
+
*/
|
|
13
|
+
export declare function collectProfileObservations(logTexts: readonly string[], resolveRoute: (route: string) => string): ProfileObservations;
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { parseRequestProfileLine, REQUEST_PROFILE_PREFIX } from "./line.mjs";
|
|
2
|
+
/**
|
|
3
|
+
* Collect exact repeated-query scopes and valid request/worker diagnostics from run logs. Worker
|
|
4
|
+
* lines are recognized by the compact `"kind":"pg-worker-profile"` form `JSON.stringify` writes.
|
|
5
|
+
*/
|
|
6
|
+
export function collectProfileObservations(logTexts, resolveRoute) {
|
|
7
|
+
const observations = {
|
|
8
|
+
requestProfileCount: 0,
|
|
9
|
+
workerProfileCount: 0,
|
|
10
|
+
malformedRequestProfileCount: 0,
|
|
11
|
+
malformedWorkerProfileCount: 0,
|
|
12
|
+
routeScopes: new Set(),
|
|
13
|
+
workerScopes: new Set(),
|
|
14
|
+
};
|
|
15
|
+
for (const logText of logTexts) {
|
|
16
|
+
for (const line of logText.split('\n')) {
|
|
17
|
+
if (line.includes('"kind":"pg-worker-profile"')) {
|
|
18
|
+
collectWorkerLine(line, observations);
|
|
19
|
+
}
|
|
20
|
+
else if (line.includes(REQUEST_PROFILE_PREFIX)) {
|
|
21
|
+
collectRequestLine(line, observations, resolveRoute);
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
return observations;
|
|
26
|
+
}
|
|
27
|
+
function collectRequestLine(line, observations, resolveRoute) {
|
|
28
|
+
const parsed = parseRequestProfileLine(line);
|
|
29
|
+
if (parsed === undefined) {
|
|
30
|
+
observations.malformedRequestProfileCount += 1;
|
|
31
|
+
return;
|
|
32
|
+
}
|
|
33
|
+
observations.requestProfileCount += 1;
|
|
34
|
+
const resolvedRoute = resolveRoute(parsed.route);
|
|
35
|
+
for (const { annotation } of parsed.repeats) {
|
|
36
|
+
observations.routeScopes.add(JSON.stringify([annotation, resolvedRoute]));
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
function collectWorkerLine(line, observations) {
|
|
40
|
+
const marker = line.indexOf('"kind":"pg-worker-profile"');
|
|
41
|
+
const start = line.lastIndexOf('{', marker);
|
|
42
|
+
if (start === -1) {
|
|
43
|
+
observations.malformedWorkerProfileCount += 1;
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
let report;
|
|
47
|
+
try {
|
|
48
|
+
report = JSON.parse(line.slice(start));
|
|
49
|
+
}
|
|
50
|
+
catch {
|
|
51
|
+
observations.malformedWorkerProfileCount += 1;
|
|
52
|
+
return;
|
|
53
|
+
}
|
|
54
|
+
const root = asRecord(report);
|
|
55
|
+
if (root?.kind !== 'pg-worker-profile' || !collectWorkerProfile(root.profile, observations)) {
|
|
56
|
+
observations.malformedWorkerProfileCount += 1;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
function collectWorkerProfile(profileValue, observations) {
|
|
60
|
+
const profile = asRecord(profileValue);
|
|
61
|
+
if (!profile)
|
|
62
|
+
return false;
|
|
63
|
+
const identity = asRecord(profile.identity);
|
|
64
|
+
const summary = asRecord(profile.summary);
|
|
65
|
+
const queue = identity?.queue;
|
|
66
|
+
const jobs = Array.isArray(identity?.jobs) ? identity.jobs : [];
|
|
67
|
+
const validJobs = jobs.length > 0 &&
|
|
68
|
+
jobs.every((jobValue) => {
|
|
69
|
+
const job = asRecord(jobValue);
|
|
70
|
+
return typeof job?.name === 'string' && job.name.trim() !== '';
|
|
71
|
+
});
|
|
72
|
+
const jobNames = validJobs ? jobs.map((jobValue) => jobValue.name) : [];
|
|
73
|
+
const repeats = summary?.repeats;
|
|
74
|
+
const repeatEntries = Array.isArray(repeats) ? repeats : [];
|
|
75
|
+
const validRepeats = Array.isArray(repeats) &&
|
|
76
|
+
repeatEntries.every((repeatValue) => {
|
|
77
|
+
const repeat = asRecord(repeatValue);
|
|
78
|
+
return (typeof repeat?.annotation === 'string' &&
|
|
79
|
+
repeat.annotation.trim() !== '' &&
|
|
80
|
+
Number.isInteger(repeat.count) &&
|
|
81
|
+
repeat.count >= 2);
|
|
82
|
+
});
|
|
83
|
+
const valid = typeof queue === 'string' && queue.trim() !== '' && validJobs && validRepeats;
|
|
84
|
+
if (valid) {
|
|
85
|
+
observations.workerProfileCount += 1;
|
|
86
|
+
for (const jobName of jobNames) {
|
|
87
|
+
for (const repeatValue of repeatEntries) {
|
|
88
|
+
const { annotation } = repeatValue;
|
|
89
|
+
observations.workerScopes.add(JSON.stringify([annotation, queue, jobName]));
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
let childrenValid = profile.children === undefined;
|
|
94
|
+
if (Array.isArray(profile.children)) {
|
|
95
|
+
childrenValid = true;
|
|
96
|
+
for (const child of profile.children) {
|
|
97
|
+
if (!collectWorkerProfile(child, observations))
|
|
98
|
+
childrenValid = false;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return valid && childrenValid;
|
|
102
|
+
}
|
|
103
|
+
function asRecord(value) {
|
|
104
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
105
|
+
? value
|
|
106
|
+
: undefined;
|
|
107
|
+
}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { RepeatBaselineEntry } from './baseline.mts';
|
|
2
|
+
/** A report-only candidate containing only the absent scopes from one baseline entry. */
|
|
3
|
+
export interface StaleBaselineCandidate {
|
|
4
|
+
index: number;
|
|
5
|
+
entry: RepeatBaselineEntry;
|
|
6
|
+
fullyStale: boolean;
|
|
7
|
+
}
|
|
8
|
+
/** Report-only candidates. Missing diagnostic kinds are never treated as evidence of absence. */
|
|
9
|
+
export interface StaleReport {
|
|
10
|
+
logCount: number;
|
|
11
|
+
requestProfileCount: number;
|
|
12
|
+
workerProfileCount: number;
|
|
13
|
+
malformedRequestProfileCount: number;
|
|
14
|
+
malformedWorkerProfileCount: number;
|
|
15
|
+
sufficient: boolean;
|
|
16
|
+
stale: StaleBaselineCandidate[];
|
|
17
|
+
}
|
|
18
|
+
/** One complete run is sufficient when it contains every diagnostic kind the baseline uses. */
|
|
19
|
+
export declare const MIN_STALE_EVIDENCE_LOGS = 1;
|
|
20
|
+
/** Report scopes absent from complete-run request and worker profile logs. */
|
|
21
|
+
export declare function buildStaleReport(baseline: readonly RepeatBaselineEntry[], logTexts: readonly string[], resolveRoute: (route: string) => string): StaleReport;
|
|
22
|
+
/** Return copies of entries with only missing named scopes, preserving baseline order. */
|
|
23
|
+
export declare function findStaleBaselineEntries(baseline: readonly RepeatBaselineEntry[], observedRouteScopes: ReadonlySet<string>, observedWorkerScopes: ReadonlySet<string>): StaleBaselineCandidate[];
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import { collectProfileObservations } from "./observations.mjs";
|
|
2
|
+
/** One complete run is sufficient when it contains every diagnostic kind the baseline uses. */
|
|
3
|
+
export const MIN_STALE_EVIDENCE_LOGS = 1;
|
|
4
|
+
/** Report scopes absent from complete-run request and worker profile logs. */
|
|
5
|
+
export function buildStaleReport(baseline, logTexts, resolveRoute) {
|
|
6
|
+
const observed = collectProfileObservations(logTexts, resolveRoute);
|
|
7
|
+
const requiresRequests = baseline.some((entry) => entry.routes.length > 0);
|
|
8
|
+
const requiresWorkers = baseline.some((entry) => (entry.workers?.length ?? 0) > 0);
|
|
9
|
+
const sufficient = logTexts.length >= MIN_STALE_EVIDENCE_LOGS &&
|
|
10
|
+
(observed.requestProfileCount > 0 || observed.workerProfileCount > 0) &&
|
|
11
|
+
(!requiresRequests || observed.requestProfileCount > 0) &&
|
|
12
|
+
(!requiresWorkers || observed.workerProfileCount > 0) &&
|
|
13
|
+
observed.malformedRequestProfileCount === 0 &&
|
|
14
|
+
observed.malformedWorkerProfileCount === 0;
|
|
15
|
+
const routeScopes = observed.requestProfileCount > 0 && observed.malformedRequestProfileCount === 0
|
|
16
|
+
? observed.routeScopes
|
|
17
|
+
: new Set(baseline.flatMap((entry) => entry.routes.map((route) => JSON.stringify([entry.annotation, route]))));
|
|
18
|
+
const workerScopes = observed.workerProfileCount > 0 && observed.malformedWorkerProfileCount === 0
|
|
19
|
+
? observed.workerScopes
|
|
20
|
+
: new Set(baseline.flatMap((entry) => (entry.workers ?? []).map((worker) => JSON.stringify([entry.annotation, worker.queue, worker.job]))));
|
|
21
|
+
return {
|
|
22
|
+
logCount: logTexts.length,
|
|
23
|
+
requestProfileCount: observed.requestProfileCount,
|
|
24
|
+
workerProfileCount: observed.workerProfileCount,
|
|
25
|
+
malformedRequestProfileCount: observed.malformedRequestProfileCount,
|
|
26
|
+
malformedWorkerProfileCount: observed.malformedWorkerProfileCount,
|
|
27
|
+
sufficient,
|
|
28
|
+
stale: findStaleBaselineEntries(baseline, routeScopes, workerScopes),
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
/** Return copies of entries with only missing named scopes, preserving baseline order. */
|
|
32
|
+
export function findStaleBaselineEntries(baseline, observedRouteScopes, observedWorkerScopes) {
|
|
33
|
+
return baseline.flatMap((entry, index) => {
|
|
34
|
+
const routes = entry.routes.filter((route) => !observedRouteScopes.has(JSON.stringify([entry.annotation, route])));
|
|
35
|
+
const workers = (entry.workers ?? []).filter((worker) => !observedWorkerScopes.has(JSON.stringify([entry.annotation, worker.queue, worker.job])));
|
|
36
|
+
if (routes.length === 0 && workers.length === 0)
|
|
37
|
+
return [];
|
|
38
|
+
const total = entry.routes.length + (entry.workers?.length ?? 0);
|
|
39
|
+
const stale = routes.length + workers.length;
|
|
40
|
+
return [
|
|
41
|
+
{
|
|
42
|
+
index,
|
|
43
|
+
entry: {
|
|
44
|
+
...entry,
|
|
45
|
+
routes,
|
|
46
|
+
...(entry.workers === undefined ? {} : { workers }),
|
|
47
|
+
},
|
|
48
|
+
fullyStale: stale === total,
|
|
49
|
+
},
|
|
50
|
+
];
|
|
51
|
+
});
|
|
52
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** One annotation that ran more than once within a request or worker job. */
|
|
2
|
+
export interface RepeatedAnnotation {
|
|
3
|
+
annotation: string;
|
|
4
|
+
count: number;
|
|
5
|
+
}
|
|
6
|
+
/** Structural shape of a per-request query summary; any compatible telemetry summary fits. */
|
|
7
|
+
export interface RequestQuerySummary {
|
|
8
|
+
totalQueries: number;
|
|
9
|
+
serialDepth: number;
|
|
10
|
+
repeats: readonly RepeatedAnnotation[];
|
|
11
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vouchington-tooling",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.67.0",
|
|
4
4
|
"description": "Vouchington CLI and extractable tooling libraries.",
|
|
5
5
|
"homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
|
|
6
6
|
"bugs": {
|
|
@@ -421,6 +421,11 @@
|
|
|
421
421
|
"import": "./dist/postgres-test-faults/index.mjs",
|
|
422
422
|
"default": "./dist/postgres-test-faults/index.mjs"
|
|
423
423
|
},
|
|
424
|
+
"./request-query-profile": {
|
|
425
|
+
"types": "./dist/request-query-profile/index.d.mts",
|
|
426
|
+
"import": "./dist/request-query-profile/index.mjs",
|
|
427
|
+
"default": "./dist/request-query-profile/index.mjs"
|
|
428
|
+
},
|
|
424
429
|
"./package.json": "./package.json",
|
|
425
430
|
"./basic-auth-doc-sync": {
|
|
426
431
|
"types": "./dist/basic-auth-doc-sync/index.d.mts",
|
|
Binary file
|