@volter/incident-match 0.0.0-stage → 1.0.1

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 CHANGED
@@ -1,3 +1,11 @@
1
- # Temporary Holding Version
1
+ # @volter/incident-match
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Fuzzy incident matching: whether a World replicated a real incident. It takes a World and the incident's URL where it
4
+ was found, reads the incident through that vendor's real API and the World's twin of the vendor through the same API,
5
+ and answers whether the World holds a match.
6
+
7
+ ```bash
8
+ incident-match https://acme.sentry.io/issues/4211/ --world .
9
+ ```
10
+
11
+ The design is [Replicating an issue](../../docs/contributing/architecture.md#replicating-an-issue).
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export declare function main(argv: string[]): Promise<number>;
@@ -0,0 +1,41 @@
1
+ #!/usr/bin/env node
2
+ // `incident-match <incident URL> [--world <dir>] [--json]` (architecture, "Replicating an issue"): exits 0 on a match,
3
+ // 1 on no match, 2 when either side cannot be read.
4
+ import { realpathSync } from 'node:fs';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { parseArgs } from 'node:util';
7
+ import { MATCH_AT, matchIncident } from "./index.js";
8
+ const USAGE = 'incident-match <incident URL> [--world <dir>] [--json]';
9
+ function show(result) {
10
+ const pct = (n) => `${Math.round(n * 100)}%`;
11
+ const side = (v) => (Array.isArray(v) ? `[${v.join(', ')}]` : JSON.stringify(v));
12
+ const lines = [`${result.match ? 'match' : 'no match'} ${pct(result.score)} (matches at ${pct(MATCH_AT)})`, `incident ${result.incident.vendor} ${result.incident.kind}: ${result.incident.title} ${result.incident.url}`];
13
+ if (!result.closest)
14
+ return [...lines, `world nothing of its kind among ${result.candidates} objects`].join('\n');
15
+ lines.push(`closest ${result.closest.url} (of ${result.candidates})`);
16
+ for (const f of result.closest.features)
17
+ lines.push(` ${pct(f.score).padStart(4)} ${f.name} (×${f.weight})\n incident ${side(f.incident)}\n world ${side(f.world)}`);
18
+ return lines.join('\n');
19
+ }
20
+ export async function main(argv) {
21
+ const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { world: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
22
+ if (values.help) {
23
+ process.stdout.write(`${USAGE}\n`);
24
+ return 0;
25
+ }
26
+ if (positionals.length !== 1) {
27
+ process.stderr.write(`${USAGE}\n`);
28
+ return 2;
29
+ }
30
+ try {
31
+ const result = await matchIncident(positionals[0], { ...(values.world ? { world: values.world } : {}) });
32
+ process.stdout.write(`${values.json ? JSON.stringify(result, null, 2) : show(result)}\n`);
33
+ return result.match ? 0 : 1;
34
+ }
35
+ catch (error) {
36
+ process.stderr.write(`incident-match: ${error instanceof Error ? error.message : String(error)}\n`);
37
+ return 2;
38
+ }
39
+ }
40
+ if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url))
41
+ process.exitCode = await main(process.argv.slice(2));
@@ -0,0 +1,27 @@
1
+ /** A feature of an object: `text` compares tokens, `set` compares items, `exact` compares the whole value. */
2
+ export type Feature = {
3
+ name: string;
4
+ weight: number;
5
+ kind: 'text' | 'set' | 'exact';
6
+ value: string | string[];
7
+ };
8
+ /** One feature of a scored pair: its two sides, parameterized, and its score. */
9
+ export type FeatureScore = {
10
+ name: string;
11
+ weight: number;
12
+ incident: string | string[];
13
+ world: string | string[];
14
+ score: number;
15
+ };
16
+ /** The threshold a World's object matches the incident's at; the readings it stands on are architecture's ("Replicating
17
+ * an issue"): the four bench tasks' unchanged apps at 100%, their real fixes at 38% or below. */
18
+ export declare const MATCH_AT = 0.8;
19
+ /** A value with its occurrence's particulars replaced by their kind. */
20
+ export declare function parameterize(value: string): string;
21
+ /** One feature's score over its two sides. */
22
+ export declare function featureScore(kind: Feature['kind'], incident: string | string[], world: string | string[]): number;
23
+ /** The incident's object scored against one of the World's, feature by feature: the two must name the same features. */
24
+ export declare function scorePair(incident: Feature[], world: Feature[]): {
25
+ score: number;
26
+ features: FeatureScore[];
27
+ };
@@ -0,0 +1,62 @@
1
+ // The one fuzzy rule (architecture, "Replicating an issue"): a reader gives each object its features, and an object's
2
+ // score is the weighted mean of its features' scores. Values are parameterized first, as Sentry groups errors
3
+ // (getsentry `grouping/parameterization.py`), so two occurrences of one failure compare equal and two failures do not.
4
+ /** The threshold a World's object matches the incident's at; the readings it stands on are architecture's ("Replicating
5
+ * an issue"): the four bench tasks' unchanged apps at 100%, their real fixes at 38% or below. */
6
+ export const MATCH_AT = 0.8;
7
+ const PATTERNS = [
8
+ // an email keeps its domain: whose mailbox it is, never which person (a generated guest's address is its app's)
9
+ [/[A-Za-z0-9._%+-]+@([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,})/g, (m) => `<email@${m.slice(m.indexOf('@') + 1).toLowerCase()}>`],
10
+ // a URL keeps its path: the route is the app's, the host the deployment's
11
+ [/\bhttps?:\/\/[^\s/"'<>]+/g, () => '<origin>'],
12
+ [/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, () => '<uuid>'],
13
+ [/\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?\b/g, () => '<date>'],
14
+ [/\b(?:0x)?(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{8,}\b/gi, () => '<hex>'],
15
+ // an identifier's token: a run of 16 or more letters and digits holding both (a minted id, a session, a key)
16
+ [/\b(?=[A-Za-z0-9]*\d)(?=[A-Za-z0-9]*[A-Za-z])[A-Za-z0-9]{16,}\b/g, () => '<id>'],
17
+ [/\b\d+(?:\.\d+)?\b/g, () => '<int>'],
18
+ ];
19
+ /** A value with its occurrence's particulars replaced by their kind. */
20
+ export function parameterize(value) {
21
+ let out = value;
22
+ for (const [pattern, replace] of PATTERNS)
23
+ out = out.replace(pattern, replace);
24
+ return out.trim();
25
+ }
26
+ const tokens = (value) => parameterize(value).toLowerCase().match(/<[^>]+>|[a-z_$][a-z0-9_$]*|[^\sa-z0-9_$<>]/g) ?? [];
27
+ // the overlap of two multisets (Dice's coefficient): both empty is equal
28
+ function overlap(a, b) {
29
+ if (a.length === 0 && b.length === 0)
30
+ return 1;
31
+ const counts = new Map();
32
+ for (const x of a)
33
+ counts.set(x, (counts.get(x) ?? 0) + 1);
34
+ let common = 0;
35
+ for (const x of b) {
36
+ const n = counts.get(x) ?? 0;
37
+ if (n > 0) {
38
+ common++;
39
+ counts.set(x, n - 1);
40
+ }
41
+ }
42
+ return (2 * common) / (a.length + b.length);
43
+ }
44
+ /** One feature's score over its two sides. */
45
+ export function featureScore(kind, incident, world) {
46
+ const list = (v) => (Array.isArray(v) ? v : [v]).map((x) => parameterize(x)).filter((x) => x !== '');
47
+ if (kind === 'exact')
48
+ return list(incident).join('\n') === list(world).join('\n') ? 1 : 0;
49
+ if (kind === 'set')
50
+ return overlap([...new Set(list(incident))], [...new Set(list(world))]);
51
+ return overlap(tokens(list(incident).join(' ')), tokens(list(world).join(' ')));
52
+ }
53
+ /** The incident's object scored against one of the World's, feature by feature: the two must name the same features. */
54
+ export function scorePair(incident, world) {
55
+ const features = incident.map((f) => {
56
+ const other = world.find((w) => w.name === f.name);
57
+ const side = (v) => (Array.isArray(v) ? v.map(parameterize) : parameterize(v ?? ''));
58
+ return { name: f.name, weight: f.weight, incident: side(f.value), world: side(other?.value), score: other ? featureScore(f.kind, f.value, other.value) : 0 };
59
+ });
60
+ const total = features.reduce((n, f) => n + f.weight, 0);
61
+ return { score: total === 0 ? 0 : features.reduce((n, f) => n + f.weight * f.score, 0) / total, features };
62
+ }
@@ -0,0 +1,27 @@
1
+ import { type FeatureScore } from './fuzzy.js';
2
+ import type { Reader } from './reader.js';
3
+ export { parameterize, MATCH_AT, type Feature, type FeatureScore } from './fuzzy.js';
4
+ export type { Candidate, Incident, Reader } from './reader.js';
5
+ /** Every vendor's reader, each naming the incident URLs it reads. */
6
+ export declare const READERS: Reader[];
7
+ export type MatchResult = {
8
+ match: boolean;
9
+ score: number;
10
+ incident: {
11
+ url: string;
12
+ vendor: string;
13
+ kind: string;
14
+ title: string;
15
+ };
16
+ /** The World's object closest to the incident, or none where the World holds nothing of its kind. */
17
+ closest: {
18
+ url: string;
19
+ features: FeatureScore[];
20
+ } | null;
21
+ candidates: number;
22
+ };
23
+ /** Whether the World at `world` (default: the cwd's) holds the incident at `incidentUrl`. */
24
+ export declare function matchIncident(incidentUrl: string, opts?: {
25
+ world?: string;
26
+ env?: Record<string, string | undefined>;
27
+ }): Promise<MatchResult>;
@@ -0,0 +1,32 @@
1
+ // Fuzzy incident matching (ADR 0036, "Replicating an issue"; architecture, "Replicating an issue"): whether a World
2
+ // replicated a real incident. Its two inputs are the World and the incident's URL where it was found; it reads the
3
+ // incident there and the World's twin of that vendor live, through the same API, and holds nothing of the World's.
4
+ import { MATCH_AT, scorePair } from "./fuzzy.js";
5
+ import { posthog } from "./vendors/posthog.js";
6
+ import { resend } from "./vendors/resend.js";
7
+ import { sentry } from "./vendors/sentry.js";
8
+ export { parameterize, MATCH_AT } from "./fuzzy.js";
9
+ /** Every vendor's reader, each naming the incident URLs it reads. */
10
+ export const READERS = [sentry, posthog, resend];
11
+ /** Whether the World at `world` (default: the cwd's) holds the incident at `incidentUrl`. */
12
+ export async function matchIncident(incidentUrl, opts = {}) {
13
+ const url = new URL(incidentUrl);
14
+ const reader = READERS.find((r) => r.reads(url));
15
+ if (!reader)
16
+ throw new Error(`no reader reads ${incidentUrl}: incident-match reads a Sentry issue or trace, a PostHog event or person, or a Resend email, by its URL`);
17
+ const incident = await reader.incident(url, opts.env ?? process.env);
18
+ const candidates = await reader.world(opts.world, incident);
19
+ let best = null;
20
+ for (const candidate of candidates) {
21
+ for (const occurrence of incident.occurrences) {
22
+ const scored = scorePair(occurrence, candidate.features);
23
+ if (!best || scored.score > best.score)
24
+ best = { url: candidate.url, ...scored };
25
+ }
26
+ }
27
+ return {
28
+ match: best !== null && best.score >= MATCH_AT, score: best?.score ?? 0,
29
+ incident: { url: incidentUrl, vendor: reader.vendor, kind: incident.kind, title: incident.title },
30
+ closest: best ? { url: best.url, features: best.features } : null, candidates: candidates.length,
31
+ };
32
+ }
@@ -0,0 +1,45 @@
1
+ import type { Feature } from './fuzzy.js';
2
+ /** An object either side holds: where it is, and its features. */
3
+ export type Candidate = {
4
+ url: string;
5
+ features: Feature[];
6
+ };
7
+ /** The incident as its reader read it: its kind, what it is called there, and each occurrence the vendor holds of it
8
+ * (an issue's events), any one of which a World's object may match. */
9
+ export type Incident = {
10
+ kind: string;
11
+ title: string;
12
+ occurrences: Feature[][];
13
+ };
14
+ export type Reader = {
15
+ vendor: string;
16
+ /** Whether this reader reads the incident at `url`. */
17
+ reads(url: URL): boolean;
18
+ incident(url: URL, env: Record<string, string | undefined>): Promise<Incident>;
19
+ /** The World's objects of the incident's kind, read at its twin. */
20
+ world(root: string | undefined, incident: Incident): Promise<Candidate[]>;
21
+ };
22
+ /** A JSON read of a vendor's API with its bearer credential, refused by name on any answer but 200. */
23
+ export declare function getJson(url: string, token: string): Promise<{
24
+ body: unknown;
25
+ headers: Headers;
26
+ }>;
27
+ /** Every page of a vendor's list, from `url` to its end, so no list is read cut: each page read with `getJson`, then the
28
+ * next as the vendor names it (`next` answers its URL, or nothing at the last page). */
29
+ export declare function pages(url: string, token: string, next: (page: {
30
+ body: unknown;
31
+ headers: Headers;
32
+ }) => string | undefined): AsyncGenerator<unknown>;
33
+ /** Sentry's next page: its Link header's `rel="next"` with `results="true"` (https://docs.sentry.io/api/pagination/). */
34
+ export declare function sentryNext({ headers }: {
35
+ headers: Headers;
36
+ }): string | undefined;
37
+ /** PostHog's next page: its list's `next`, the next page's URL, null at the last page. */
38
+ export declare const posthogNext: ({ body }: {
39
+ body: unknown;
40
+ }) => string | undefined;
41
+ /** A required variable of the matcher's environment, refused by name when unset. */
42
+ export declare function required(env: Record<string, string | undefined>, name: string, why: string): string;
43
+ export declare const record: (v: unknown) => Record<string, unknown>;
44
+ export declare const list: (v: unknown) => unknown[];
45
+ export declare const text: (v: unknown) => string;
@@ -0,0 +1,41 @@
1
+ /** A JSON read of a vendor's API with its bearer credential, refused by name on any answer but 200. */
2
+ export async function getJson(url, token) {
3
+ const response = await fetch(url, { headers: { authorization: `Bearer ${token}`, accept: 'application/json' } });
4
+ if (response.status !== 200)
5
+ throw new Error(`GET ${url} answered ${response.status}: ${(await response.text()).slice(0, 300)}`);
6
+ return { body: await response.json(), headers: response.headers };
7
+ }
8
+ /** Every page of a vendor's list, from `url` to its end, so no list is read cut: each page read with `getJson`, then the
9
+ * next as the vendor names it (`next` answers its URL, or nothing at the last page). */
10
+ export async function* pages(url, token, next) {
11
+ const seen = new Set();
12
+ for (let at = url; at !== undefined;) {
13
+ if (seen.has(at))
14
+ throw new Error(`the list at ${url} names a page it has already given (${at})`);
15
+ seen.add(at);
16
+ const page = await getJson(at, token);
17
+ yield page.body;
18
+ at = next(page);
19
+ }
20
+ }
21
+ /** Sentry's next page: its Link header's `rel="next"` with `results="true"` (https://docs.sentry.io/api/pagination/). */
22
+ export function sentryNext({ headers }) {
23
+ for (const part of (headers.get('link') ?? '').split(/,(?=\s*<)/)) {
24
+ const hit = /<([^>]+)>/.exec(part);
25
+ if (hit && /rel="next"/.test(part) && /results="true"/.test(part))
26
+ return hit[1];
27
+ }
28
+ return undefined;
29
+ }
30
+ /** PostHog's next page: its list's `next`, the next page's URL, null at the last page. */
31
+ export const posthogNext = ({ body }) => text(record(body).next) || undefined;
32
+ /** A required variable of the matcher's environment, refused by name when unset. */
33
+ export function required(env, name, why) {
34
+ const value = env[name];
35
+ if (!value)
36
+ throw new Error(`${name} is not set: ${why}`);
37
+ return value;
38
+ }
39
+ export const record = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
40
+ export const list = (v) => (Array.isArray(v) ? v : []);
41
+ export const text = (v) => (typeof v === 'string' ? v : v === undefined || v === null ? '' : String(v));
@@ -0,0 +1,2 @@
1
+ import { type Reader } from '../reader.js';
2
+ export declare const posthog: Reader;
@@ -0,0 +1,78 @@
1
+ import { getJson, list, pages, posthogNext, record, required, text } from "../reader.js";
2
+ import { twinAccess } from "../world-side.js";
3
+ const WORLD_SETTINGS = { POSTHOG_PERSONAL_API_KEY: 'personal_api_key', POSTHOG_PROJECT_ID: 'project_id' };
4
+ const KEY_WHY = "the real PostHog's personal API key, with query:read and person:read";
5
+ // every event since well before any World's clock: the API's default window is the last day
6
+ const SINCE = '2000-01-01T00:00:00Z';
7
+ // `https://us.posthog.com/project/<id>/events/<uuid>/<timestamp>` and `…/project/<id>/person/<distinct id>`
8
+ function parse(url) {
9
+ const match = /\/project\/(\d+)\/(events|person)\/([^/]+)/.exec(url.pathname);
10
+ if (!match)
11
+ return null;
12
+ return match[2] === 'events' ? { project: match[1], event: decodeURIComponent(match[3]) } : { project: match[1], person: decodeURIComponent(match[3]) };
13
+ }
14
+ function eventFeatures(event) {
15
+ const e = record(event), p = record(e.properties);
16
+ const exception = record(list(p.$exception_list)[0]);
17
+ return [
18
+ { name: 'event', weight: 3, kind: 'exact', value: text(e.event) },
19
+ { name: 'page', weight: 2, kind: 'text', value: text(p.$current_url) || text(p.$pathname) },
20
+ { name: 'exception', weight: 2, kind: 'text', value: `${text(exception.type)} ${text(exception.value)}`.trim() },
21
+ { name: 'properties', weight: 1, kind: 'set', value: Object.keys(p).filter((k) => !k.startsWith('$')) },
22
+ ];
23
+ }
24
+ function personFeatures(events) {
25
+ const rows = events.map(record);
26
+ return [
27
+ { name: 'events', weight: 3, kind: 'set', value: rows.map((e) => text(e.event)) },
28
+ { name: 'pages', weight: 1, kind: 'set', value: rows.map((e) => text(record(e.properties).$current_url)).filter(Boolean) },
29
+ ];
30
+ }
31
+ const eventsUrl = (base, project, filter = '') => `${base}/api/projects/${project}/events/?after=${encodeURIComponent(SINCE)}&limit=100${filter}`;
32
+ // every event of the list, page by page to its end
33
+ async function allEvents(url, key) {
34
+ const out = [];
35
+ for await (const page of pages(url, key, posthogNext))
36
+ out.push(...list(record(page).results));
37
+ return out;
38
+ }
39
+ export const posthog = {
40
+ vendor: 'posthog',
41
+ reads: (url) => /(^|\.)posthog\.com$/.test(url.hostname) && parse(url) !== null,
42
+ async incident(url, env) {
43
+ const at = parse(url);
44
+ const key = required(env, 'POSTHOG_PERSONAL_API_KEY', KEY_WHY);
45
+ const base = `${url.protocol}//${url.host}`;
46
+ if (at.person) {
47
+ const events = await allEvents(eventsUrl(base, at.project, `&distinct_id=${encodeURIComponent(at.person)}`), key);
48
+ if (events.length === 0)
49
+ throw new Error(`PostHog holds no events of ${at.person} in project ${at.project}`);
50
+ return { kind: 'person', title: `person ${at.person}`, occurrences: [personFeatures(events)] };
51
+ }
52
+ const { body } = await getJson(`${base}/api/projects/${at.project}/events/${encodeURIComponent(at.event)}/`, key);
53
+ return { kind: 'event', title: `${text(record(body).event)} ${at.event}`, occurrences: [eventFeatures(body)] };
54
+ },
55
+ async world(root, incident) {
56
+ const out = [];
57
+ for (const access of await twinAccess(root, 'posthog', WORLD_SETTINGS)) {
58
+ const key = access.env.POSTHOG_PERSONAL_API_KEY, project = access.env.POSTHOG_PROJECT_ID;
59
+ if (!key || !project)
60
+ continue;
61
+ const base = access.url.replace(/\/+$/, '');
62
+ const events = await allEvents(eventsUrl(base, project), key);
63
+ if (incident.kind === 'person') {
64
+ const byPerson = new Map();
65
+ for (const e of events) {
66
+ const id = text(record(e).distinct_id);
67
+ byPerson.set(id, [...(byPerson.get(id) ?? []), e]);
68
+ }
69
+ for (const [id, own] of byPerson)
70
+ out.push({ url: `${base}/project/${project}/person/${encodeURIComponent(id)}`, features: personFeatures(own) });
71
+ continue;
72
+ }
73
+ for (const e of events)
74
+ out.push({ url: `${base}/project/${project}/events/${text(record(e).id)}`, features: eventFeatures(e) });
75
+ }
76
+ return out;
77
+ },
78
+ };
@@ -0,0 +1,2 @@
1
+ import { type Reader } from '../reader.js';
2
+ export declare const resend: Reader;
@@ -0,0 +1,46 @@
1
+ import { getJson, list, record, required, text } from "../reader.js";
2
+ import { twinAccess } from "../world-side.js";
3
+ const WORLD_SETTINGS = { RESEND_API_KEY: 'token' };
4
+ const KEY_WHY = "the real Resend's API key, as its SDK reads it";
5
+ // where the real API answers: Resend's own, or the one its SDK is pointed at (`RESEND_BASE_URL`, resend-node src/resend.ts)
6
+ const api = (env) => (env.RESEND_BASE_URL ?? 'https://api.resend.com').replace(/\/+$/, '');
7
+ // `https://resend.com/emails/<id>`, the email's page in Resend's dashboard
8
+ const parse = (url) => (url.hostname === 'resend.com' ? /^\/emails\/([0-9a-f-]{36})\/?$/i.exec(url.pathname)?.[1] ?? null : null);
9
+ const addresses = (v) => (Array.isArray(v) ? v : v === undefined || v === null ? [] : [v]).map(text).filter(Boolean);
10
+ function emailFeatures(email) {
11
+ const e = record(email);
12
+ return [
13
+ { name: 'last event', weight: 3, kind: 'exact', value: text(e.last_event) },
14
+ { name: 'subject', weight: 2, kind: 'text', value: text(e.subject) },
15
+ { name: 'from', weight: 1, kind: 'text', value: text(e.from) },
16
+ { name: 'recipients', weight: 2, kind: 'set', value: [...addresses(e.to), ...addresses(e.cc), ...addresses(e.bcc)] },
17
+ ];
18
+ }
19
+ export const resend = {
20
+ vendor: 'resend',
21
+ reads: (url) => parse(url) !== null,
22
+ async incident(url, env) {
23
+ const id = parse(url);
24
+ const { body } = await getJson(`${api(env)}/emails/${id}`, required(env, 'RESEND_API_KEY', KEY_WHY));
25
+ return { kind: 'email', title: `${text(record(body).subject)} (${text(record(body).last_event)})`, occurrences: [emailFeatures(body)] };
26
+ },
27
+ async world(root) {
28
+ const out = [];
29
+ for (const access of await twinAccess(root, 'resend', WORLD_SETTINGS)) {
30
+ const key = access.env.RESEND_API_KEY;
31
+ if (!key)
32
+ continue;
33
+ const base = access.url.replace(/\/+$/, '');
34
+ // every page of the list (`has_more`, `after`: https://resend.com/docs/api-reference/emails/list-emails)
35
+ for (let after, more = true; more;) {
36
+ const page = record((await getJson(`${base}/emails?limit=100${after ? `&after=${encodeURIComponent(after)}` : ''}`, key)).body);
37
+ const rows = list(page.data).map(record);
38
+ for (const e of rows)
39
+ out.push({ url: `${base}/emails/${text(e.id)}`, features: emailFeatures(e) });
40
+ more = page.has_more === true && rows.length > 0;
41
+ after = text(rows[rows.length - 1]?.id);
42
+ }
43
+ }
44
+ return out;
45
+ },
46
+ };
@@ -0,0 +1,2 @@
1
+ import { type Reader } from '../reader.js';
2
+ export declare const sentry: Reader;
@@ -0,0 +1,97 @@
1
+ import { list, pages, record, required, sentryNext, text } from "../reader.js";
2
+ import { twinAccess } from "../world-side.js";
3
+ const WORLD_SETTINGS = { SENTRY_AUTH_TOKEN: 'auth_token', SENTRY_ORG: 'org' };
4
+ const TOKEN_WHY = "the real Sentry's token, as sentry-cli reads it (an auth token with event:read)";
5
+ // `https://<org>.sentry.io/issues/<id>/…`, `https://sentry.io/organizations/<org>/issues/<id>/…`, and a trace's
6
+ // `…/trace/<trace id>` under performance or explore
7
+ function parse(url) {
8
+ const sub = /^([a-z0-9-]+)\.sentry\.io$/.exec(url.hostname)?.[1];
9
+ const org = /\/organizations\/([^/]+)\//.exec(url.pathname)?.[1] ?? (sub && !['us', 'de', 'www'].includes(sub) ? sub : undefined);
10
+ if (!org)
11
+ return null;
12
+ const issue = /\/issues\/(\d+)\//.exec(`${url.pathname}/`)?.[1];
13
+ const event = /\/events\/([0-9a-f]{32})\//i.exec(`${url.pathname}/`)?.[1]?.toLowerCase();
14
+ const trace = /\/trace\/([0-9a-f]{32})\//i.exec(`${url.pathname}/`)?.[1]?.toLowerCase();
15
+ return issue || trace ? { org, ...(issue ? { issue } : {}), ...(event ? { event } : {}), ...(trace ? { trace } : {}) } : null;
16
+ }
17
+ // an error event's features, from its full body (`full=true`)
18
+ function eventFeatures(event) {
19
+ const e = record(event);
20
+ const entries = list(e.entries).map(record);
21
+ const values = list(record(entries.find((x) => x.type === 'exception')?.data).values).map(record);
22
+ const last = values[values.length - 1] ?? {};
23
+ const frames = values.flatMap((v) => list(record(v.stacktrace).frames).map(record)).filter((f) => f.inApp === true).map((f) => text(f.function)).filter(Boolean);
24
+ const tags = new Map(list(e.tags).map(record).map((t) => [text(t.key), text(t.value)]));
25
+ const requestUrl = text(record(entries.find((x) => x.type === 'request')?.data).url);
26
+ return [
27
+ { name: 'type', weight: 3, kind: 'exact', value: text(last.type) || text(record(e.metadata).type) },
28
+ { name: 'in-app frames', weight: 3, kind: 'set', value: frames },
29
+ { name: 'message', weight: 2, kind: 'text', value: text(last.value) || text(e.message) || text(e.title) },
30
+ { name: 'transaction', weight: 1, kind: 'text', value: tags.get('transaction') ?? '' },
31
+ { name: 'request route', weight: 1, kind: 'text', value: requestUrl },
32
+ ];
33
+ }
34
+ const SPAN_FIELDS = ['span.op', 'span.description', 'span.status', 'transaction', 'trace'];
35
+ const spansQuery = (base, org, query) => `${base}/api/0/organizations/${org}/events/?dataset=spans&${SPAN_FIELDS.map((f) => `field=${encodeURIComponent(f)}`).join('&')}&query=${encodeURIComponent(query)}&per_page=100`;
36
+ // the World's side is read whole: a twin's window ends at the World's frozen instant, and an app's own stamps may run a
37
+ // step ahead of it (ADR 0036 §5), so an explicit window from the epoch to far ahead holds every event the twin keeps
38
+ const WHOLE = `start=${encodeURIComponent('1970-01-01T00:00:00Z')}&end=${encodeURIComponent('9999-12-31T00:00:00Z')}`;
39
+ // every row of a list, page by page to its end (an envelope's `data`, or the list itself)
40
+ async function all(url, token) {
41
+ const out = [];
42
+ for await (const page of pages(url, token, sentryNext))
43
+ out.push(...(Array.isArray(page) ? page : list(record(page).data)));
44
+ return out;
45
+ }
46
+ const failed = (status) => status !== '' && status !== 'ok' && status !== 'unknown';
47
+ // a trace's features, from its spans
48
+ function traceFeatures(spans) {
49
+ const rows = spans.map(record);
50
+ return [
51
+ { name: 'failing spans', weight: 3, kind: 'set', value: rows.filter((s) => failed(text(s['span.status']))).map((s) => `${text(s['span.op'])} ${text(s['span.description'])} ${text(s['span.status'])}`) },
52
+ { name: 'transactions', weight: 1, kind: 'set', value: rows.map((s) => text(s.transaction)).filter(Boolean) },
53
+ { name: 'operations', weight: 1, kind: 'set', value: rows.map((s) => text(s['span.op'])).filter(Boolean) },
54
+ ];
55
+ }
56
+ export const sentry = {
57
+ vendor: 'sentry',
58
+ reads: (url) => /(^|\.)sentry\.io$/.test(url.hostname) && parse(url) !== null,
59
+ async incident(url, env) {
60
+ const at = parse(url);
61
+ const token = required(env, 'SENTRY_AUTH_TOKEN', TOKEN_WHY);
62
+ const base = (env.SENTRY_URL ?? 'https://sentry.io').replace(/\/+$/, '');
63
+ if (at.trace) {
64
+ const spans = await all(spansQuery(base, at.org, `trace:${at.trace}`), token);
65
+ if (spans.length === 0)
66
+ throw new Error(`Sentry holds no spans of trace ${at.trace} in ${at.org}`);
67
+ return { kind: 'trace', title: `trace ${at.trace}`, occurrences: [traceFeatures(spans)] };
68
+ }
69
+ const events = (await all(`${base}/api/0/organizations/${at.org}/issues/${at.issue}/events/?full=true&per_page=100`, token)).filter((e) => !at.event || text(record(e).eventID ?? record(e).id).replace(/-/g, '').toLowerCase() === at.event);
70
+ if (events.length === 0)
71
+ throw new Error(`Sentry holds no events of issue ${at.issue}${at.event ? ` named ${at.event}` : ''} in ${at.org}`);
72
+ return { kind: 'issue', title: text(record(events[0]).title) || `issue ${at.issue}`, occurrences: events.map(eventFeatures) };
73
+ },
74
+ async world(root, incident) {
75
+ const out = [];
76
+ for (const access of await twinAccess(root, 'sentry', WORLD_SETTINGS)) {
77
+ const token = access.env.SENTRY_AUTH_TOKEN, org = access.env.SENTRY_ORG;
78
+ if (!token || !org)
79
+ continue;
80
+ const base = access.url.replace(/\/+$/, '');
81
+ if (incident.kind === 'trace') {
82
+ const traces = [...new Set((await all(`${spansQuery(base, org, '!span.status:ok')}&${WHOLE}`, token)).map((s) => text(record(s).trace)).filter(Boolean))];
83
+ for (const trace of traces) {
84
+ const spans = await all(`${spansQuery(base, org, `trace:${trace}`)}&${WHOLE}`, token);
85
+ out.push({ url: `${base}/organizations/${org}/explore/traces/trace/${trace}/`, features: traceFeatures(spans) });
86
+ }
87
+ continue;
88
+ }
89
+ for (const issue of (await all(`${base}/api/0/organizations/${org}/issues/?query=&limit=100&${WHOLE}`, token)).map(record)) {
90
+ const events = await all(`${base}/api/0/organizations/${org}/issues/${text(issue.id)}/events/?full=true&per_page=100&${WHOLE}`, token);
91
+ for (const event of events)
92
+ out.push({ url: `${base}/organizations/${org}/issues/${text(issue.id)}/events/${text(record(event).eventID ?? record(event).id)}/`, features: eventFeatures(event) });
93
+ }
94
+ }
95
+ return out;
96
+ },
97
+ };
@@ -0,0 +1,9 @@
1
+ /** One organization's view of a vendor's twin: where it answers and the World's settings for it. */
2
+ export type TwinAccess = {
3
+ organization: string;
4
+ url: string;
5
+ env: Record<string, string>;
6
+ };
7
+ /** The twin of `vendor` in the World at `root`, once per organization, with the settings `references` names
8
+ * (`{ SENTRY_AUTH_TOKEN: 'auth_token' }`: a variable and the twin's field it is issued from). */
9
+ export declare function twinAccess(root: string | undefined, vendor: string, references: Record<string, string>): Promise<TwinAccess[]>;
@@ -0,0 +1,32 @@
1
+ // The World's side (architecture, "Replicating an issue"): the World itself, opened with its SDK, never a file it
2
+ // exported. A vendor's twin is read at its address, with the World's own credentials for it, issued to the matcher as
3
+ // a deployment of its own through `.env.world` references, once per organization the World declares and its default:
4
+ // the app's organization is the app's, not the matcher's to know.
5
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
6
+ import { tmpdir } from 'node:os';
7
+ import { join } from 'node:path';
8
+ import { World, worldConfigPath } from '@volter/world';
9
+ /** The twin of `vendor` in the World at `root`, once per organization, with the settings `references` names
10
+ * (`{ SENTRY_AUTH_TOKEN: 'auth_token' }`: a variable and the twin's field it is issued from). */
11
+ export async function twinAccess(root, vendor, references) {
12
+ const world = World.open(root === undefined ? {} : { root });
13
+ const twin = world.twin(vendor);
14
+ if (!twin.url)
15
+ throw new Error(`the World at ${world.root} is not running: its ${vendor} twin has no address (\`volter world up\`)`);
16
+ const config = JSON.parse(readFileSync(worldConfigPath(world.root), 'utf8'));
17
+ const organizations = ['default', ...(config.organizations ?? []).map((o) => o.id)];
18
+ const out = [];
19
+ for (const organization of [...new Set(organizations)]) {
20
+ const dir = mkdtempSync(join(tmpdir(), 'incident-match-'));
21
+ try {
22
+ const lines = [`VOLTER_ORGANIZATION=${organization}`, ...Object.entries(references).map(([name, field]) => `${name}=\${{ ${vendor}.${field} }}`)];
23
+ writeFileSync(join(dir, '.env.world'), `${lines.join('\n')}\n`);
24
+ const rendered = await world.env({ cwd: dir, outputRoot: join(dir, 'out'), templates: [{ template: '.env.world', target: '.env' }], deployment: 'incident-match' });
25
+ out.push({ organization, url: twin.url, env: rendered.env });
26
+ }
27
+ finally {
28
+ rmSync(dir, { recursive: true, force: true });
29
+ }
30
+ }
31
+ return out;
32
+ }
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@volter/incident-match",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.1",
4
+ "description": "Fuzzy incident matching: whether a World replicated a real incident, read through the vendors' own APIs at both; docs/contributing/architecture.md, \"Replicating an issue\".",
5
+ "keywords": [
6
+ "twin",
7
+ "world",
8
+ "incident",
9
+ "sentry",
10
+ "posthog"
11
+ ],
12
+ "author": "Volter (https://github.com/volter-ai)",
13
+ "license": "Apache-2.0",
14
+ "publishConfig": {
15
+ "access": "public"
16
+ },
17
+ "type": "module",
18
+ "bin": {
19
+ "incident-match": "dist/src/cli.js"
20
+ },
21
+ "exports": {
22
+ ".": {
23
+ "types": "./dist/src/index.d.ts",
24
+ "default": "./dist/src/index.js"
25
+ }
26
+ },
27
+ "files": [
28
+ "src",
29
+ "dist"
30
+ ],
31
+ "dependencies": {
32
+ "@volter/world": "3.0.222"
33
+ },
34
+ "scripts": {
35
+ "build": "node ../../scripts/publish/build.mjs",
36
+ "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
37
+ "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
38
+ },
39
+ "homepage": "https://world.volter.ai/docs/README",
40
+ "packageManager": "pnpm@12.15.0",
41
+ "devEngines": {
42
+ "packageManager": {
43
+ "name": "pnpm",
44
+ "version": "12.15.0",
45
+ "onFail": "error"
46
+ }
47
+ }
48
+ }
package/src/cli.ts ADDED
@@ -0,0 +1,35 @@
1
+ #!/usr/bin/env node
2
+ // `incident-match <incident URL> [--world <dir>] [--json]` (architecture, "Replicating an issue"): exits 0 on a match,
3
+ // 1 on no match, 2 when either side cannot be read.
4
+ import { realpathSync } from 'node:fs';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { parseArgs } from 'node:util';
7
+ import { MATCH_AT, matchIncident, type MatchResult } from './index.ts';
8
+
9
+ const USAGE = 'incident-match <incident URL> [--world <dir>] [--json]';
10
+
11
+ function show(result: MatchResult): string {
12
+ const pct = (n: number): string => `${Math.round(n * 100)}%`;
13
+ const side = (v: string | string[]): string => (Array.isArray(v) ? `[${v.join(', ')}]` : JSON.stringify(v));
14
+ const lines = [`${result.match ? 'match' : 'no match'} ${pct(result.score)} (matches at ${pct(MATCH_AT)})`, `incident ${result.incident.vendor} ${result.incident.kind}: ${result.incident.title} ${result.incident.url}`];
15
+ if (!result.closest) return [...lines, `world nothing of its kind among ${result.candidates} objects`].join('\n');
16
+ lines.push(`closest ${result.closest.url} (of ${result.candidates})`);
17
+ for (const f of result.closest.features) lines.push(` ${pct(f.score).padStart(4)} ${f.name} (×${f.weight})\n incident ${side(f.incident)}\n world ${side(f.world)}`);
18
+ return lines.join('\n');
19
+ }
20
+
21
+ export async function main(argv: string[]): Promise<number> {
22
+ const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { world: { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } } });
23
+ if (values.help) { process.stdout.write(`${USAGE}\n`); return 0; }
24
+ if (positionals.length !== 1) { process.stderr.write(`${USAGE}\n`); return 2; }
25
+ try {
26
+ const result = await matchIncident(positionals[0]!, { ...(values.world ? { world: values.world } : {}) });
27
+ process.stdout.write(`${values.json ? JSON.stringify(result, null, 2) : show(result)}\n`);
28
+ return result.match ? 0 : 1;
29
+ } catch (error) {
30
+ process.stderr.write(`incident-match: ${error instanceof Error ? error.message : String(error)}\n`);
31
+ return 2;
32
+ }
33
+ }
34
+
35
+ if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) process.exitCode = await main(process.argv.slice(2));
package/src/fuzzy.ts ADDED
@@ -0,0 +1,63 @@
1
+ // The one fuzzy rule (architecture, "Replicating an issue"): a reader gives each object its features, and an object's
2
+ // score is the weighted mean of its features' scores. Values are parameterized first, as Sentry groups errors
3
+ // (getsentry `grouping/parameterization.py`), so two occurrences of one failure compare equal and two failures do not.
4
+
5
+ /** A feature of an object: `text` compares tokens, `set` compares items, `exact` compares the whole value. */
6
+ export type Feature = { name: string; weight: number; kind: 'text' | 'set' | 'exact'; value: string | string[] };
7
+ /** One feature of a scored pair: its two sides, parameterized, and its score. */
8
+ export type FeatureScore = { name: string; weight: number; incident: string | string[]; world: string | string[]; score: number };
9
+
10
+ /** The threshold a World's object matches the incident's at; the readings it stands on are architecture's ("Replicating
11
+ * an issue"): the four bench tasks' unchanged apps at 100%, their real fixes at 38% or below. */
12
+ export const MATCH_AT = 0.8;
13
+
14
+ const PATTERNS: Array<[RegExp, (m: string) => string]> = [
15
+ // an email keeps its domain: whose mailbox it is, never which person (a generated guest's address is its app's)
16
+ [/[A-Za-z0-9._%+-]+@([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,})/g, (m) => `<email@${m.slice(m.indexOf('@') + 1).toLowerCase()}>`],
17
+ // a URL keeps its path: the route is the app's, the host the deployment's
18
+ [/\bhttps?:\/\/[^\s/"'<>]+/g, () => '<origin>'],
19
+ [/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, () => '<uuid>'],
20
+ [/\b\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?\b/g, () => '<date>'],
21
+ [/\b(?:0x)?(?=[0-9a-f]*\d)(?=[0-9a-f]*[a-f])[0-9a-f]{8,}\b/gi, () => '<hex>'],
22
+ // an identifier's token: a run of 16 or more letters and digits holding both (a minted id, a session, a key)
23
+ [/\b(?=[A-Za-z0-9]*\d)(?=[A-Za-z0-9]*[A-Za-z])[A-Za-z0-9]{16,}\b/g, () => '<id>'],
24
+ [/\b\d+(?:\.\d+)?\b/g, () => '<int>'],
25
+ ];
26
+
27
+ /** A value with its occurrence's particulars replaced by their kind. */
28
+ export function parameterize(value: string): string {
29
+ let out = value;
30
+ for (const [pattern, replace] of PATTERNS) out = out.replace(pattern, replace);
31
+ return out.trim();
32
+ }
33
+
34
+ const tokens = (value: string): string[] => parameterize(value).toLowerCase().match(/<[^>]+>|[a-z_$][a-z0-9_$]*|[^\sa-z0-9_$<>]/g) ?? [];
35
+
36
+ // the overlap of two multisets (Dice's coefficient): both empty is equal
37
+ function overlap(a: string[], b: string[]): number {
38
+ if (a.length === 0 && b.length === 0) return 1;
39
+ const counts = new Map<string, number>();
40
+ for (const x of a) counts.set(x, (counts.get(x) ?? 0) + 1);
41
+ let common = 0;
42
+ for (const x of b) { const n = counts.get(x) ?? 0; if (n > 0) { common++; counts.set(x, n - 1); } }
43
+ return (2 * common) / (a.length + b.length);
44
+ }
45
+
46
+ /** One feature's score over its two sides. */
47
+ export function featureScore(kind: Feature['kind'], incident: string | string[], world: string | string[]): number {
48
+ const list = (v: string | string[]): string[] => (Array.isArray(v) ? v : [v]).map((x) => parameterize(x)).filter((x) => x !== '');
49
+ if (kind === 'exact') return list(incident).join('\n') === list(world).join('\n') ? 1 : 0;
50
+ if (kind === 'set') return overlap([...new Set(list(incident))], [...new Set(list(world))]);
51
+ return overlap(tokens(list(incident).join(' ')), tokens(list(world).join(' ')));
52
+ }
53
+
54
+ /** The incident's object scored against one of the World's, feature by feature: the two must name the same features. */
55
+ export function scorePair(incident: Feature[], world: Feature[]): { score: number; features: FeatureScore[] } {
56
+ const features = incident.map((f) => {
57
+ const other = world.find((w) => w.name === f.name);
58
+ const side = (v: string | string[] | undefined): string | string[] => (Array.isArray(v) ? v.map(parameterize) : parameterize(v ?? ''));
59
+ return { name: f.name, weight: f.weight, incident: side(f.value), world: side(other?.value), score: other ? featureScore(f.kind, f.value, other.value) : 0 };
60
+ });
61
+ const total = features.reduce((n, f) => n + f.weight, 0);
62
+ return { score: total === 0 ? 0 : features.reduce((n, f) => n + f.weight * f.score, 0) / total, features };
63
+ }
package/src/index.ts ADDED
@@ -0,0 +1,42 @@
1
+ // Fuzzy incident matching (ADR 0036, "Replicating an issue"; architecture, "Replicating an issue"): whether a World
2
+ // replicated a real incident. Its two inputs are the World and the incident's URL where it was found; it reads the
3
+ // incident there and the World's twin of that vendor live, through the same API, and holds nothing of the World's.
4
+ import { MATCH_AT, scorePair, type FeatureScore } from './fuzzy.ts';
5
+ import type { Reader } from './reader.ts';
6
+ import { posthog } from './vendors/posthog.ts';
7
+ import { resend } from './vendors/resend.ts';
8
+ import { sentry } from './vendors/sentry.ts';
9
+
10
+ export { parameterize, MATCH_AT, type Feature, type FeatureScore } from './fuzzy.ts';
11
+ export type { Candidate, Incident, Reader } from './reader.ts';
12
+
13
+ /** Every vendor's reader, each naming the incident URLs it reads. */
14
+ export const READERS: Reader[] = [sentry, posthog, resend];
15
+
16
+ export type MatchResult = {
17
+ match: boolean; score: number; incident: { url: string; vendor: string; kind: string; title: string };
18
+ /** The World's object closest to the incident, or none where the World holds nothing of its kind. */
19
+ closest: { url: string; features: FeatureScore[] } | null;
20
+ candidates: number;
21
+ };
22
+
23
+ /** Whether the World at `world` (default: the cwd's) holds the incident at `incidentUrl`. */
24
+ export async function matchIncident(incidentUrl: string, opts: { world?: string; env?: Record<string, string | undefined> } = {}): Promise<MatchResult> {
25
+ const url = new URL(incidentUrl);
26
+ const reader = READERS.find((r) => r.reads(url));
27
+ if (!reader) throw new Error(`no reader reads ${incidentUrl}: incident-match reads a Sentry issue or trace, a PostHog event or person, or a Resend email, by its URL`);
28
+ const incident = await reader.incident(url, opts.env ?? process.env);
29
+ const candidates = await reader.world(opts.world, incident);
30
+ let best: { url: string; score: number; features: FeatureScore[] } | null = null;
31
+ for (const candidate of candidates) {
32
+ for (const occurrence of incident.occurrences) {
33
+ const scored = scorePair(occurrence, candidate.features);
34
+ if (!best || scored.score > best.score) best = { url: candidate.url, ...scored };
35
+ }
36
+ }
37
+ return {
38
+ match: best !== null && best.score >= MATCH_AT, score: best?.score ?? 0,
39
+ incident: { url: incidentUrl, vendor: reader.vendor, kind: incident.kind, title: incident.title },
40
+ closest: best ? { url: best.url, features: best.features } : null, candidates: candidates.length,
41
+ };
42
+ }
package/src/reader.ts ADDED
@@ -0,0 +1,61 @@
1
+ // What a vendor's reader is (architecture, "Replicating an issue"): the incident URLs it reads, the incident read at the
2
+ // real API, and the World's objects of the incident's kind read at the twin through the same paths.
3
+ import type { Feature } from './fuzzy.ts';
4
+
5
+ /** An object either side holds: where it is, and its features. */
6
+ export type Candidate = { url: string; features: Feature[] };
7
+ /** The incident as its reader read it: its kind, what it is called there, and each occurrence the vendor holds of it
8
+ * (an issue's events), any one of which a World's object may match. */
9
+ export type Incident = { kind: string; title: string; occurrences: Feature[][] };
10
+
11
+ export type Reader = {
12
+ vendor: string;
13
+ /** Whether this reader reads the incident at `url`. */
14
+ reads(url: URL): boolean;
15
+ incident(url: URL, env: Record<string, string | undefined>): Promise<Incident>;
16
+ /** The World's objects of the incident's kind, read at its twin. */
17
+ world(root: string | undefined, incident: Incident): Promise<Candidate[]>;
18
+ };
19
+
20
+ /** A JSON read of a vendor's API with its bearer credential, refused by name on any answer but 200. */
21
+ export async function getJson(url: string, token: string): Promise<{ body: unknown; headers: Headers }> {
22
+ const response = await fetch(url, { headers: { authorization: `Bearer ${token}`, accept: 'application/json' } });
23
+ if (response.status !== 200) throw new Error(`GET ${url} answered ${response.status}: ${(await response.text()).slice(0, 300)}`);
24
+ return { body: await response.json(), headers: response.headers };
25
+ }
26
+
27
+ /** Every page of a vendor's list, from `url` to its end, so no list is read cut: each page read with `getJson`, then the
28
+ * next as the vendor names it (`next` answers its URL, or nothing at the last page). */
29
+ export async function* pages(url: string, token: string, next: (page: { body: unknown; headers: Headers }) => string | undefined): AsyncGenerator<unknown> {
30
+ const seen = new Set<string>();
31
+ for (let at: string | undefined = url; at !== undefined;) {
32
+ if (seen.has(at)) throw new Error(`the list at ${url} names a page it has already given (${at})`);
33
+ seen.add(at);
34
+ const page = await getJson(at, token);
35
+ yield page.body;
36
+ at = next(page);
37
+ }
38
+ }
39
+
40
+ /** Sentry's next page: its Link header's `rel="next"` with `results="true"` (https://docs.sentry.io/api/pagination/). */
41
+ export function sentryNext({ headers }: { headers: Headers }): string | undefined {
42
+ for (const part of (headers.get('link') ?? '').split(/,(?=\s*<)/)) {
43
+ const hit = /<([^>]+)>/.exec(part);
44
+ if (hit && /rel="next"/.test(part) && /results="true"/.test(part)) return hit[1];
45
+ }
46
+ return undefined;
47
+ }
48
+
49
+ /** PostHog's next page: its list's `next`, the next page's URL, null at the last page. */
50
+ export const posthogNext = ({ body }: { body: unknown }): string | undefined => text(record(body).next) || undefined;
51
+
52
+ /** A required variable of the matcher's environment, refused by name when unset. */
53
+ export function required(env: Record<string, string | undefined>, name: string, why: string): string {
54
+ const value = env[name];
55
+ if (!value) throw new Error(`${name} is not set: ${why}`);
56
+ return value;
57
+ }
58
+
59
+ export const record = (v: unknown): Record<string, unknown> => (v && typeof v === 'object' && !Array.isArray(v) ? v as Record<string, unknown> : {});
60
+ export const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : []);
61
+ export const text = (v: unknown): string => (typeof v === 'string' ? v : v === undefined || v === null ? '' : String(v));
@@ -0,0 +1,79 @@
1
+ // PostHog's reader (architecture, "Replicating an issue"). An event is matched by its name, the page it happened on and
2
+ // its properties' shape, an exception by its type and message beside them; a person is read as their events, matched
3
+ // by which events they had and on which pages.
4
+ import type { Feature } from '../fuzzy.ts';
5
+ import { getJson, list, pages, posthogNext, record, required, text, type Candidate, type Reader } from '../reader.ts';
6
+ import { twinAccess } from '../world-side.ts';
7
+
8
+ const WORLD_SETTINGS = { POSTHOG_PERSONAL_API_KEY: 'personal_api_key', POSTHOG_PROJECT_ID: 'project_id' };
9
+ const KEY_WHY = "the real PostHog's personal API key, with query:read and person:read";
10
+ // every event since well before any World's clock: the API's default window is the last day
11
+ const SINCE = '2000-01-01T00:00:00Z';
12
+
13
+ // `https://us.posthog.com/project/<id>/events/<uuid>/<timestamp>` and `…/project/<id>/person/<distinct id>`
14
+ function parse(url: URL): { project: string; event?: string; person?: string } | null {
15
+ const match = /\/project\/(\d+)\/(events|person)\/([^/]+)/.exec(url.pathname);
16
+ if (!match) return null;
17
+ return match[2] === 'events' ? { project: match[1]!, event: decodeURIComponent(match[3]!) } : { project: match[1]!, person: decodeURIComponent(match[3]!) };
18
+ }
19
+
20
+ function eventFeatures(event: unknown): Feature[] {
21
+ const e = record(event), p = record(e.properties);
22
+ const exception = record(list(p.$exception_list)[0]);
23
+ return [
24
+ { name: 'event', weight: 3, kind: 'exact', value: text(e.event) },
25
+ { name: 'page', weight: 2, kind: 'text', value: text(p.$current_url) || text(p.$pathname) },
26
+ { name: 'exception', weight: 2, kind: 'text', value: `${text(exception.type)} ${text(exception.value)}`.trim() },
27
+ { name: 'properties', weight: 1, kind: 'set', value: Object.keys(p).filter((k) => !k.startsWith('$')) },
28
+ ];
29
+ }
30
+
31
+ function personFeatures(events: unknown[]): Feature[] {
32
+ const rows = events.map(record);
33
+ return [
34
+ { name: 'events', weight: 3, kind: 'set', value: rows.map((e) => text(e.event)) },
35
+ { name: 'pages', weight: 1, kind: 'set', value: rows.map((e) => text(record(e.properties).$current_url)).filter(Boolean) },
36
+ ];
37
+ }
38
+
39
+ const eventsUrl = (base: string, project: string, filter = ''): string => `${base}/api/projects/${project}/events/?after=${encodeURIComponent(SINCE)}&limit=100${filter}`;
40
+ // every event of the list, page by page to its end
41
+ async function allEvents(url: string, key: string): Promise<unknown[]> {
42
+ const out: unknown[] = [];
43
+ for await (const page of pages(url, key, posthogNext)) out.push(...list(record(page).results));
44
+ return out;
45
+ }
46
+
47
+ export const posthog: Reader = {
48
+ vendor: 'posthog',
49
+ reads: (url) => /(^|\.)posthog\.com$/.test(url.hostname) && parse(url) !== null,
50
+ async incident(url, env) {
51
+ const at = parse(url)!;
52
+ const key = required(env, 'POSTHOG_PERSONAL_API_KEY', KEY_WHY);
53
+ const base = `${url.protocol}//${url.host}`;
54
+ if (at.person) {
55
+ const events = await allEvents(eventsUrl(base, at.project, `&distinct_id=${encodeURIComponent(at.person)}`), key);
56
+ if (events.length === 0) throw new Error(`PostHog holds no events of ${at.person} in project ${at.project}`);
57
+ return { kind: 'person', title: `person ${at.person}`, occurrences: [personFeatures(events)] };
58
+ }
59
+ const { body } = await getJson(`${base}/api/projects/${at.project}/events/${encodeURIComponent(at.event!)}/`, key);
60
+ return { kind: 'event', title: `${text(record(body).event)} ${at.event}`, occurrences: [eventFeatures(body)] };
61
+ },
62
+ async world(root, incident) {
63
+ const out: Candidate[] = [];
64
+ for (const access of await twinAccess(root, 'posthog', WORLD_SETTINGS)) {
65
+ const key = access.env.POSTHOG_PERSONAL_API_KEY, project = access.env.POSTHOG_PROJECT_ID;
66
+ if (!key || !project) continue;
67
+ const base = access.url.replace(/\/+$/, '');
68
+ const events = await allEvents(eventsUrl(base, project), key);
69
+ if (incident.kind === 'person') {
70
+ const byPerson = new Map<string, unknown[]>();
71
+ for (const e of events) { const id = text(record(e).distinct_id); byPerson.set(id, [...(byPerson.get(id) ?? []), e]); }
72
+ for (const [id, own] of byPerson) out.push({ url: `${base}/project/${project}/person/${encodeURIComponent(id)}`, features: personFeatures(own) });
73
+ continue;
74
+ }
75
+ for (const e of events) out.push({ url: `${base}/project/${project}/events/${text(record(e).id)}`, features: eventFeatures(e) });
76
+ }
77
+ return out;
78
+ },
79
+ };
@@ -0,0 +1,53 @@
1
+ // Resend's reader (architecture, "Replicating an issue"): a mail provider's log. An email is matched by its subject,
2
+ // its sender, its recipients' form (whose mailbox, never which person) and how it ended (`last_event`: a bounce is the
3
+ // failure a mail server's log shows).
4
+ import type { Feature } from '../fuzzy.ts';
5
+ import { getJson, list, record, required, text, type Candidate, type Reader } from '../reader.ts';
6
+ import { twinAccess } from '../world-side.ts';
7
+
8
+ const WORLD_SETTINGS = { RESEND_API_KEY: 'token' };
9
+ const KEY_WHY = "the real Resend's API key, as its SDK reads it";
10
+ // where the real API answers: Resend's own, or the one its SDK is pointed at (`RESEND_BASE_URL`, resend-node src/resend.ts)
11
+ const api = (env: Record<string, string | undefined>): string => (env.RESEND_BASE_URL ?? 'https://api.resend.com').replace(/\/+$/, '');
12
+
13
+ // `https://resend.com/emails/<id>`, the email's page in Resend's dashboard
14
+ const parse = (url: URL): string | null => (url.hostname === 'resend.com' ? /^\/emails\/([0-9a-f-]{36})\/?$/i.exec(url.pathname)?.[1] ?? null : null);
15
+
16
+ const addresses = (v: unknown): string[] => (Array.isArray(v) ? v : v === undefined || v === null ? [] : [v]).map(text).filter(Boolean);
17
+
18
+ function emailFeatures(email: unknown): Feature[] {
19
+ const e = record(email);
20
+ return [
21
+ { name: 'last event', weight: 3, kind: 'exact', value: text(e.last_event) },
22
+ { name: 'subject', weight: 2, kind: 'text', value: text(e.subject) },
23
+ { name: 'from', weight: 1, kind: 'text', value: text(e.from) },
24
+ { name: 'recipients', weight: 2, kind: 'set', value: [...addresses(e.to), ...addresses(e.cc), ...addresses(e.bcc)] },
25
+ ];
26
+ }
27
+
28
+ export const resend: Reader = {
29
+ vendor: 'resend',
30
+ reads: (url) => parse(url) !== null,
31
+ async incident(url, env) {
32
+ const id = parse(url)!;
33
+ const { body } = await getJson(`${api(env)}/emails/${id}`, required(env, 'RESEND_API_KEY', KEY_WHY));
34
+ return { kind: 'email', title: `${text(record(body).subject)} (${text(record(body).last_event)})`, occurrences: [emailFeatures(body)] };
35
+ },
36
+ async world(root) {
37
+ const out: Candidate[] = [];
38
+ for (const access of await twinAccess(root, 'resend', WORLD_SETTINGS)) {
39
+ const key = access.env.RESEND_API_KEY;
40
+ if (!key) continue;
41
+ const base = access.url.replace(/\/+$/, '');
42
+ // every page of the list (`has_more`, `after`: https://resend.com/docs/api-reference/emails/list-emails)
43
+ for (let after: string | undefined, more = true; more;) {
44
+ const page = record((await getJson(`${base}/emails?limit=100${after ? `&after=${encodeURIComponent(after)}` : ''}`, key)).body);
45
+ const rows = list(page.data).map(record);
46
+ for (const e of rows) out.push({ url: `${base}/emails/${text(e.id)}`, features: emailFeatures(e) });
47
+ more = page.has_more === true && rows.length > 0;
48
+ after = text(rows[rows.length - 1]?.id);
49
+ }
50
+ }
51
+ return out;
52
+ },
53
+ };
@@ -0,0 +1,103 @@
1
+ // Sentry's reader (architecture, "Replicating an issue"). An issue is read as its events, each an occurrence, and
2
+ // matched by what Sentry groups an error by: its type, its in-app frames and its parameterized message, with the
3
+ // transaction and the request's route beside them. A trace is read as its spans (Explore's spans dataset), and matched
4
+ // by its failing spans, its transactions and its operations.
5
+ import type { Feature } from '../fuzzy.ts';
6
+ import { list, pages, record, required, sentryNext, text, type Candidate, type Reader } from '../reader.ts';
7
+ import { twinAccess } from '../world-side.ts';
8
+
9
+ const WORLD_SETTINGS = { SENTRY_AUTH_TOKEN: 'auth_token', SENTRY_ORG: 'org' };
10
+ const TOKEN_WHY = "the real Sentry's token, as sentry-cli reads it (an auth token with event:read)";
11
+
12
+ // `https://<org>.sentry.io/issues/<id>/…`, `https://sentry.io/organizations/<org>/issues/<id>/…`, and a trace's
13
+ // `…/trace/<trace id>` under performance or explore
14
+ function parse(url: URL): { org: string; issue?: string; event?: string; trace?: string } | null {
15
+ const sub = /^([a-z0-9-]+)\.sentry\.io$/.exec(url.hostname)?.[1];
16
+ const org = /\/organizations\/([^/]+)\//.exec(url.pathname)?.[1] ?? (sub && !['us', 'de', 'www'].includes(sub) ? sub : undefined);
17
+ if (!org) return null;
18
+ const issue = /\/issues\/(\d+)\//.exec(`${url.pathname}/`)?.[1];
19
+ const event = /\/events\/([0-9a-f]{32})\//i.exec(`${url.pathname}/`)?.[1]?.toLowerCase();
20
+ const trace = /\/trace\/([0-9a-f]{32})\//i.exec(`${url.pathname}/`)?.[1]?.toLowerCase();
21
+ return issue || trace ? { org, ...(issue ? { issue } : {}), ...(event ? { event } : {}), ...(trace ? { trace } : {}) } : null;
22
+ }
23
+
24
+ // an error event's features, from its full body (`full=true`)
25
+ function eventFeatures(event: unknown): Feature[] {
26
+ const e = record(event);
27
+ const entries = list(e.entries).map(record);
28
+ const values = list(record(entries.find((x) => x.type === 'exception')?.data).values).map(record);
29
+ const last = values[values.length - 1] ?? {};
30
+ const frames = values.flatMap((v) => list(record(v.stacktrace).frames).map(record)).filter((f) => f.inApp === true).map((f) => text(f.function)).filter(Boolean);
31
+ const tags = new Map(list(e.tags).map(record).map((t) => [text(t.key), text(t.value)]));
32
+ const requestUrl = text(record(entries.find((x) => x.type === 'request')?.data).url);
33
+ return [
34
+ { name: 'type', weight: 3, kind: 'exact', value: text(last.type) || text(record(e.metadata).type) },
35
+ { name: 'in-app frames', weight: 3, kind: 'set', value: frames },
36
+ { name: 'message', weight: 2, kind: 'text', value: text(last.value) || text(e.message) || text(e.title) },
37
+ { name: 'transaction', weight: 1, kind: 'text', value: tags.get('transaction') ?? '' },
38
+ { name: 'request route', weight: 1, kind: 'text', value: requestUrl },
39
+ ];
40
+ }
41
+
42
+ const SPAN_FIELDS = ['span.op', 'span.description', 'span.status', 'transaction', 'trace'];
43
+ const spansQuery = (base: string, org: string, query: string): string =>
44
+ `${base}/api/0/organizations/${org}/events/?dataset=spans&${SPAN_FIELDS.map((f) => `field=${encodeURIComponent(f)}`).join('&')}&query=${encodeURIComponent(query)}&per_page=100`;
45
+ // the World's side is read whole: a twin's window ends at the World's frozen instant, and an app's own stamps may run a
46
+ // step ahead of it (ADR 0036 §5), so an explicit window from the epoch to far ahead holds every event the twin keeps
47
+ const WHOLE = `start=${encodeURIComponent('1970-01-01T00:00:00Z')}&end=${encodeURIComponent('9999-12-31T00:00:00Z')}`;
48
+ // every row of a list, page by page to its end (an envelope's `data`, or the list itself)
49
+ async function all(url: string, token: string): Promise<unknown[]> {
50
+ const out: unknown[] = [];
51
+ for await (const page of pages(url, token, sentryNext)) out.push(...(Array.isArray(page) ? page : list(record(page).data)));
52
+ return out;
53
+ }
54
+ const failed = (status: string): boolean => status !== '' && status !== 'ok' && status !== 'unknown';
55
+
56
+ // a trace's features, from its spans
57
+ function traceFeatures(spans: unknown[]): Feature[] {
58
+ const rows = spans.map(record);
59
+ return [
60
+ { name: 'failing spans', weight: 3, kind: 'set', value: rows.filter((s) => failed(text(s['span.status']))).map((s) => `${text(s['span.op'])} ${text(s['span.description'])} ${text(s['span.status'])}`) },
61
+ { name: 'transactions', weight: 1, kind: 'set', value: rows.map((s) => text(s.transaction)).filter(Boolean) },
62
+ { name: 'operations', weight: 1, kind: 'set', value: rows.map((s) => text(s['span.op'])).filter(Boolean) },
63
+ ];
64
+ }
65
+
66
+ export const sentry: Reader = {
67
+ vendor: 'sentry',
68
+ reads: (url) => /(^|\.)sentry\.io$/.test(url.hostname) && parse(url) !== null,
69
+ async incident(url, env) {
70
+ const at = parse(url)!;
71
+ const token = required(env, 'SENTRY_AUTH_TOKEN', TOKEN_WHY);
72
+ const base = (env.SENTRY_URL ?? 'https://sentry.io').replace(/\/+$/, '');
73
+ if (at.trace) {
74
+ const spans = await all(spansQuery(base, at.org, `trace:${at.trace}`), token);
75
+ if (spans.length === 0) throw new Error(`Sentry holds no spans of trace ${at.trace} in ${at.org}`);
76
+ return { kind: 'trace', title: `trace ${at.trace}`, occurrences: [traceFeatures(spans)] };
77
+ }
78
+ const events = (await all(`${base}/api/0/organizations/${at.org}/issues/${at.issue}/events/?full=true&per_page=100`, token)).filter((e) => !at.event || text(record(e).eventID ?? record(e).id).replace(/-/g, '').toLowerCase() === at.event);
79
+ if (events.length === 0) throw new Error(`Sentry holds no events of issue ${at.issue}${at.event ? ` named ${at.event}` : ''} in ${at.org}`);
80
+ return { kind: 'issue', title: text(record(events[0]).title) || `issue ${at.issue}`, occurrences: events.map(eventFeatures) };
81
+ },
82
+ async world(root, incident) {
83
+ const out: Candidate[] = [];
84
+ for (const access of await twinAccess(root, 'sentry', WORLD_SETTINGS)) {
85
+ const token = access.env.SENTRY_AUTH_TOKEN, org = access.env.SENTRY_ORG;
86
+ if (!token || !org) continue;
87
+ const base = access.url.replace(/\/+$/, '');
88
+ if (incident.kind === 'trace') {
89
+ const traces = [...new Set((await all(`${spansQuery(base, org, '!span.status:ok')}&${WHOLE}`, token)).map((s) => text(record(s).trace)).filter(Boolean))];
90
+ for (const trace of traces) {
91
+ const spans = await all(`${spansQuery(base, org, `trace:${trace}`)}&${WHOLE}`, token);
92
+ out.push({ url: `${base}/organizations/${org}/explore/traces/trace/${trace}/`, features: traceFeatures(spans) });
93
+ }
94
+ continue;
95
+ }
96
+ for (const issue of (await all(`${base}/api/0/organizations/${org}/issues/?query=&limit=100&${WHOLE}`, token)).map(record)) {
97
+ const events = await all(`${base}/api/0/organizations/${org}/issues/${text(issue.id)}/events/?full=true&per_page=100&${WHOLE}`, token);
98
+ for (const event of events) out.push({ url: `${base}/organizations/${org}/issues/${text(issue.id)}/events/${text(record(event).eventID ?? record(event).id)}/`, features: eventFeatures(event) });
99
+ }
100
+ }
101
+ return out;
102
+ },
103
+ };
@@ -0,0 +1,34 @@
1
+ // The World's side (architecture, "Replicating an issue"): the World itself, opened with its SDK, never a file it
2
+ // exported. A vendor's twin is read at its address, with the World's own credentials for it, issued to the matcher as
3
+ // a deployment of its own through `.env.world` references, once per organization the World declares and its default:
4
+ // the app's organization is the app's, not the matcher's to know.
5
+ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
6
+ import { tmpdir } from 'node:os';
7
+ import { join } from 'node:path';
8
+ import { World, worldConfigPath } from '@volter/world';
9
+
10
+ /** One organization's view of a vendor's twin: where it answers and the World's settings for it. */
11
+ export type TwinAccess = { organization: string; url: string; env: Record<string, string> };
12
+
13
+ /** The twin of `vendor` in the World at `root`, once per organization, with the settings `references` names
14
+ * (`{ SENTRY_AUTH_TOKEN: 'auth_token' }`: a variable and the twin's field it is issued from). */
15
+ export async function twinAccess(root: string | undefined, vendor: string, references: Record<string, string>): Promise<TwinAccess[]> {
16
+ const world = World.open(root === undefined ? {} : { root });
17
+ const twin = world.twin(vendor);
18
+ if (!twin.url) throw new Error(`the World at ${world.root} is not running: its ${vendor} twin has no address (\`volter world up\`)`);
19
+ const config = JSON.parse(readFileSync(worldConfigPath(world.root), 'utf8')) as { organizations?: Array<{ id: string }> };
20
+ const organizations = ['default', ...(config.organizations ?? []).map((o) => o.id)];
21
+ const out: TwinAccess[] = [];
22
+ for (const organization of [...new Set(organizations)]) {
23
+ const dir = mkdtempSync(join(tmpdir(), 'incident-match-'));
24
+ try {
25
+ const lines = [`VOLTER_ORGANIZATION=${organization}`, ...Object.entries(references).map(([name, field]) => `${name}=\${{ ${vendor}.${field} }}`)];
26
+ writeFileSync(join(dir, '.env.world'), `${lines.join('\n')}\n`);
27
+ const rendered = await world.env({ cwd: dir, outputRoot: join(dir, 'out'), templates: [{ template: '.env.world', target: '.env' }], deployment: 'incident-match' });
28
+ out.push({ organization, url: twin.url, env: rendered.env });
29
+ } finally {
30
+ rmSync(dir, { recursive: true, force: true });
31
+ }
32
+ }
33
+ return out;
34
+ }