proteum 2.1.2 → 2.1.6

package/common/dev/diagnostics.ts

@@ -1,6 +1,7 @@
 import type {
     TProteumManifest,
     TProteumManifestCommand,
+    TProteumManifestConnectedProject,
     TProteumManifestController,
     TProteumManifestDiagnostic,
     TProteumManifestLayout,
@@ -8,7 +9,7 @@ import type {
     TProteumManifestService,
 } from './proteumManifest';
 
-export const explainSectionNames = ['app', 'conventions', 'env', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'] as const;
+export const explainSectionNames = ['app', 'conventions', 'env', 'connected', 'services', 'controllers', 'commands', 'routes', 'layouts', 'diagnostics'] as const;
 
 export type TExplainSectionName = (typeof explainSectionNames)[number];
 export type THumanTextBlock = {
@@ -51,12 +52,15 @@ const formatServiceItem = (manifest: TProteumManifest, service: TProteumManifest
         return `${service.registeredName} -> ref ${service.refTo} [${service.parent}]`;
     }
 
-    const source = service.metasFilepath ? formatManifestFilepath(manifest, service.metasFilepath) : 'unknown';
-    return `${service.registeredName} -> ${service.id} (${service.metaName}) [${service.scope}] priority=${service.priority} source=${source}`;
+    const source = service.sourceFilepath ? formatManifestFilepath(manifest, service.sourceFilepath) : 'unknown';
+    return `${service.registeredName} -> ${service.className || 'unknown'} [${service.scope}] priority=${service.priority} parent=${service.parent} source=${source}`;
 };
 
+const formatConnectedProjectItem = (_manifest: TProteumManifest, connectedProject: TProteumManifestConnectedProject) =>
+    `${connectedProject.namespace} -> ${connectedProject.identityIdentifier || connectedProject.packageName || 'unknown'} controllers=${connectedProject.controllerCount} internal=${connectedProject.urlInternal || 'missing'}${connectedProject.sourceKind ? ` source=${connectedProject.sourceKind}` : ''}${connectedProject.sourceValue ? ` sourceValue=${connectedProject.sourceValue}` : ' source=missing'}${connectedProject.typingMode ? ` typing=${connectedProject.typingMode}` : ''}${connectedProject.cachedContractFilepath ? ` contract=${formatManifestFilepath(_manifest, connectedProject.cachedContractFilepath)}` : ''}`;
+
 const formatControllerItem = (manifest: TProteumManifest, controller: TProteumManifestController) =>
-    `${controller.clientAccessor} -> POST ${controller.httpPath} [${controller.scope}] input=${controller.hasInput ? 'yes' : 'no'} source=${formatManifestFilepath(manifest, controller.filepath)}${formatManifestLocation(controller.sourceLocation.line, controller.sourceLocation.column)}#${controller.methodName}`;
+    `${controller.clientAccessor} -> POST ${controller.httpPath} [${controller.scope}] input=${controller.hasInput ? 'yes' : 'no'}${controller.connectedProjectNamespace ? ` connected=${controller.connectedProjectNamespace}` : ''} source=${formatManifestFilepath(manifest, controller.filepath)}${formatManifestLocation(controller.sourceLocation.line, controller.sourceLocation.column)}#${controller.methodName}`;
 
 const formatCommandItem = (manifest: TProteumManifest, command: TProteumManifestCommand) =>
     `${command.path} -> ${command.className}.${command.methodName} [${command.scope}] source=${formatManifestFilepath(manifest, command.filepath)}${formatManifestLocation(command.sourceLocation.line, command.sourceLocation.column)}`;
@@ -90,13 +94,18 @@ const formatDiagnosticItem = (manifest: TProteumManifest, diagnostic: TProteumMa
 export const pickExplainManifestSections = (manifest: TProteumManifest, sectionNames: TExplainSectionName[]) => {
     if (sectionNames.length === 0) return manifest;
 
-    const selected: Partial<TProteumManifest> = {};
+    const selected: Record<string, unknown> = {};
 
     for (const sectionName of sectionNames) {
-        selected[sectionName] = manifest[sectionName];
+        if (sectionName === 'connected') {
+            selected.connectedProjects = manifest.connectedProjects;
+            continue;
+        }
+
+        selected[sectionName] = manifest[sectionName as keyof TProteumManifest];
     }
 
-    return selected;
+    return selected as Partial<TProteumManifest>;
 };
 
 export const buildExplainSummaryItems = (manifest: TProteumManifest) => {
@@ -108,6 +117,7 @@ export const buildExplainSummaryItems = (manifest: TProteumManifest) => {
         `Proteum manifest: ${formatManifestFilepath(manifest, `${normalizePath(manifest.app.root)}/.proteum/manifest.json`)}`,
         `App: ${manifest.app.identity.name} (${manifest.app.identity.identifier})`,
         `Env vars: ${providedRequiredEnvVariables}/${manifest.env.requiredVariables.length} required provided`,
+        `Connected projects: ${manifest.connectedProjects.length}`,
         `Services: ${manifest.services.app.length} app, ${manifest.services.routerPlugins.length} router plugins`,
         `Controllers: ${manifest.controllers.length}`,
         `Commands: ${manifest.commands.length}`,
@@ -129,9 +139,12 @@ export const buildExplainBlocks = (manifest: TProteumManifest, sectionNames: TEx
                     `root=${formatManifestFilepath(manifest, manifest.app.root)}`,
                     `coreRoot=${formatManifestFilepath(manifest, manifest.app.coreRoot)}`,
                     `identity=${formatManifestFilepath(manifest, manifest.app.identityFilepath)}`,
+                    `setup=${formatManifestFilepath(manifest, manifest.app.setupFilepath)}`,
                     `name=${manifest.app.identity.name}`,
                     `identifier=${manifest.app.identity.identifier}`,
                     `title=${manifest.app.identity.fullTitle || manifest.app.identity.title || manifest.app.identity.name}`,
+                    `transpile=${manifest.app.setup.transpile?.join(', ') || 'none'}`,
+                    `connect=${Object.keys(manifest.app.setup.connect || {}).join(', ') || 'none'}`,
                 ],
             });
             continue;
@@ -162,11 +175,20 @@ export const buildExplainBlocks = (manifest: TProteumManifest, sectionNames: TEx
                     `resolved.profile=${manifest.env.resolved.profile}`,
                     `resolved.routerPort=${manifest.env.resolved.routerPort}`,
                     `resolved.routerCurrentDomain=${manifest.env.resolved.routerCurrentDomain}`,
+                    `resolved.routerInternalUrl=${manifest.env.resolved.routerInternalUrl}`,
                 ],
             });
             continue;
         }
 
+        if (sectionName === 'connected') {
+            blocks.push({
+                title: 'Connected Projects',
+                items: manifest.connectedProjects.map((connectedProject) => formatConnectedProjectItem(manifest, connectedProject)),
+            });
+            continue;
+        }
+
         if (sectionName === 'services') {
             blocks.push(
                 {
@@ -254,9 +276,12 @@ export const buildDoctorResponse = (manifest: TProteumManifest, strict = false):
     };
 };
 
-export const buildDoctorBlocks = (manifest: TProteumManifest): THumanTextBlock[] => {
-    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error');
-    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
+export const buildDoctorBlocksFromDiagnostics = (
+    manifest: TProteumManifest,
+    diagnostics: TProteumManifestDiagnostic[],
+): THumanTextBlock[] => {
+    const errors = diagnostics.filter((diagnostic) => diagnostic.level === 'error');
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.level === 'warning');
 
     return [
         {
@@ -284,15 +309,34 @@ export const buildDoctorBlocks = (manifest: TProteumManifest): THumanTextBlock[]
     ];
 };
 
-export const renderDoctorHuman = (manifest: TProteumManifest, strict = false) => {
-    const response = buildDoctorResponse(manifest, strict);
-    if (response.diagnostics.length === 0) return 'Proteum doctor\n- No manifest diagnostics were found.';
+export const buildDoctorBlocks = (manifest: TProteumManifest) => buildDoctorBlocksFromDiagnostics(manifest, manifest.diagnostics);
+
+export const renderDoctorResponseHuman = ({
+    manifest,
+    response,
+    title,
+    emptyMessage,
+}: {
+    manifest: TProteumManifest;
+    response: TDoctorResponse;
+    title: string;
+    emptyMessage?: string;
+}) => {
+    if (response.diagnostics.length === 0) return `${title}\n- ${emptyMessage || 'No manifest diagnostics were found.'}`;
 
     return [
-        'Proteum doctor',
+        title,
         `- ${response.summary.errors} errors`,
         `- ${response.summary.warnings} warnings`,
         '',
-        ...buildDoctorBlocks(manifest).map(renderHumanBlock),
+        ...buildDoctorBlocksFromDiagnostics(manifest, response.diagnostics).map(renderHumanBlock),
     ].join('\n');
 };
+
+export const renderDoctorHuman = (manifest: TProteumManifest, strict = false) =>
+    renderDoctorResponseHuman({
+        emptyMessage: 'No manifest diagnostics were found.',
+        manifest,
+        response: buildDoctorResponse(manifest, strict),
+        title: 'Proteum doctor',
+    });

package/common/dev/inspection.ts

@@ -0,0 +1,491 @@
+import { buildExplainSummaryItems, type TDoctorResponse } from './diagnostics';
+import type { TDevConsoleLogsResponse } from './console';
+import type {
+    TProteumManifest,
+    TProteumManifestCommand,
+    TProteumManifestController,
+    TProteumManifestDiagnostic,
+    TProteumManifestLayout,
+    TProteumManifestRoute,
+    TProteumManifestScope,
+    TProteumManifestService,
+    TProteumManifestSourceLocation,
+} from './proteumManifest';
+import type { TRequestTrace, TTraceEvent } from './requestTrace';
+
+/*----------------------------------
+- TYPES
+----------------------------------*/
+
+export type TOwnerKind = 'route' | 'controller' | 'command' | 'service' | 'layout' | 'diagnostic';
+
+export type TOwnerSource = {
+    filepath: string;
+    line?: number;
+    column?: number;
+    scope?: TProteumManifestScope;
+};
+
+export type TExplainOwnerMatch = {
+    details: string[];
+    kind: TOwnerKind;
+    label: string;
+    matchedOn: string[];
+    score: number;
+    source: TOwnerSource;
+};
+
+export type TExplainOwnerResponse = {
+    matches: TExplainOwnerMatch[];
+    normalizedQuery: string;
+    query: string;
+};
+
+export type TTraceAttributionItem = {
+    kind: 'request' | 'event' | 'call' | 'sql';
+    label: string;
+    owner?: TExplainOwnerMatch;
+    reference: string;
+};
+
+export type TTraceAttributionResponse = {
+    calls: TTraceAttributionItem[];
+    events: TTraceAttributionItem[];
+    primary?: TTraceAttributionItem;
+    sqlQueries: TTraceAttributionItem[];
+};
+
+export type TDiagnoseSuspect = {
+    filepath: string;
+    label: string;
+    line?: number;
+    column?: number;
+    reasons: string[];
+    score: number;
+};
+
+export type TDiagnoseResponse = {
+    attribution?: TTraceAttributionResponse;
+    contracts: TDoctorResponse;
+    doctor: TDoctorResponse;
+    explainSummary: string[];
+    owner: TExplainOwnerResponse;
+    query: string;
+    request?: TRequestTrace;
+    serverLogs: TDevConsoleLogsResponse;
+    suspects: TDiagnoseSuspect[];
+};
+
+type TManifestEntry =
+    | { details: string[]; kind: 'command'; label: string; searchTerms: string[]; source: TOwnerSource }
+    | { details: string[]; kind: 'controller'; label: string; searchTerms: string[]; source: TOwnerSource }
+    | { details: string[]; kind: 'diagnostic'; label: string; searchTerms: string[]; source: TOwnerSource }
+    | { details: string[]; kind: 'layout'; label: string; searchTerms: string[]; source: TOwnerSource }
+    | { details: string[]; kind: 'route'; label: string; searchTerms: string[]; source: TOwnerSource }
+    | { details: string[]; kind: 'service'; label: string; searchTerms: string[]; source: TOwnerSource };
+
+type TSuspectAccumulator = {
+    column?: number;
+    filepath: string;
+    label: string;
+    line?: number;
+    reasons: Set<string>;
+    score: number;
+};
+
+/*----------------------------------
+- CONSTANTS
+----------------------------------*/
+
+const normalizeText = (value: string) => value.trim().replace(/\\/g, '/').toLowerCase();
+const tokenize = (value: string) =>
+    normalizeText(value)
+        .split(/[^a-z0-9/_.-]+/i)
+        .map((token) => token.trim())
+        .filter(Boolean);
+
+/*----------------------------------
+- HELPERS
+----------------------------------*/
+
+const toSource = (filepath: string, sourceLocation?: TProteumManifestSourceLocation, scope?: TProteumManifestScope): TOwnerSource => ({
+    filepath,
+    line: sourceLocation?.line,
+    column: sourceLocation?.column,
+    ...(scope ? { scope } : {}),
+});
+
+const pushTerm = (terms: Set<string>, value?: string) => {
+    if (!value) return;
+
+    const normalized = normalizeText(value);
+    if (!normalized) return;
+    terms.add(normalized);
+
+    const basename = normalized.split('/').pop();
+    if (basename) terms.add(basename);
+
+    for (const token of tokenize(value)) terms.add(token);
+};
+
+const createRouteEntry = (route: TProteumManifestRoute): TManifestEntry => {
+    const terms = new Set<string>();
+
+    pushTerm(terms, route.filepath);
+    pushTerm(terms, route.path);
+    pushTerm(terms, route.pathRaw);
+    pushTerm(terms, route.codeRaw);
+    pushTerm(terms, route.chunkId);
+    pushTerm(terms, route.chunkFilepath);
+    pushTerm(terms, route.kind);
+    pushTerm(terms, route.methodName);
+
+    return {
+        details: [
+            `${route.kind} ${route.methodName}`,
+            ...(route.path ? [`path=${route.path}`] : []),
+            ...(route.chunkId ? [`chunk=${route.chunkId}`] : []),
+            `setup=${route.hasSetup ? 'yes' : 'no'}`,
+        ],
+        kind: 'route',
+        label: route.path || route.pathRaw || route.chunkId || route.filepath,
+        searchTerms: [...terms],
+        source: toSource(route.filepath, route.sourceLocation, route.scope),
+    };
+};
+
+const createControllerEntry = (controller: TProteumManifestController): TManifestEntry => {
+    const terms = new Set<string>();
+
+    pushTerm(terms, controller.filepath);
+    pushTerm(terms, controller.className);
+    pushTerm(terms, controller.methodName);
+    pushTerm(terms, controller.routePath);
+    pushTerm(terms, controller.httpPath);
+    pushTerm(terms, controller.clientAccessor);
+
+    return {
+        details: [
+            controller.className,
+            `method=${controller.methodName}`,
+            `http=${controller.httpPath}`,
+            `client=${controller.clientAccessor}`,
+        ],
+        kind: 'controller',
+        label: controller.httpPath,
+        searchTerms: [...terms],
+        source: toSource(controller.filepath, controller.sourceLocation, controller.scope),
+    };
+};
+
+const createCommandEntry = (command: TProteumManifestCommand): TManifestEntry => {
+    const terms = new Set<string>();
+
+    pushTerm(terms, command.filepath);
+    pushTerm(terms, command.className);
+    pushTerm(terms, command.methodName);
+    pushTerm(terms, command.path);
+
+    return {
+        details: [command.className, `method=${command.methodName}`, `path=${command.path}`],
+        kind: 'command',
+        label: command.path,
+        searchTerms: [...terms],
+        source: toSource(command.filepath, command.sourceLocation, command.scope),
+    };
+};
+
+const createServiceEntry = (service: TProteumManifestService): TManifestEntry => {
+    const terms = new Set<string>();
+    const sourceFilepath = service.sourceFilepath || '';
+
+    pushTerm(terms, service.registeredName);
+    pushTerm(terms, service.className);
+    pushTerm(terms, service.parent);
+    pushTerm(terms, service.refTo);
+    pushTerm(terms, service.importPath);
+    pushTerm(terms, sourceFilepath);
+
+    return {
+        details: [
+            service.kind,
+            `registered=${service.registeredName}`,
+            ...(service.className ? [`class=${service.className}`] : []),
+            ...(service.importPath ? [`import=${service.importPath}`] : []),
+            ...(service.refTo ? [`ref=${service.refTo}`] : []),
+        ],
+        kind: 'service',
+        label: service.registeredName,
+        searchTerms: [...terms],
+        source: toSource(sourceFilepath || service.importPath || service.registeredName, undefined, service.scope),
+    };
+};
+
+const createLayoutEntry = (layout: TProteumManifestLayout): TManifestEntry => {
+    const terms = new Set<string>();
+
+    pushTerm(terms, layout.filepath);
+    pushTerm(terms, layout.chunkId);
+    pushTerm(terms, layout.importPath);
+
+    return {
+        details: [`chunk=${layout.chunkId}`, `depth=${layout.depth}`],
+        kind: 'layout',
+        label: layout.chunkId || layout.filepath,
+        searchTerms: [...terms],
+        source: toSource(layout.filepath, undefined, layout.scope),
+    };
+};
+
+const createDiagnosticEntry = (diagnostic: TProteumManifestDiagnostic): TManifestEntry => {
+    const terms = new Set<string>();
+
+    pushTerm(terms, diagnostic.code);
+    pushTerm(terms, diagnostic.message);
+    pushTerm(terms, diagnostic.filepath);
+    for (const related of diagnostic.relatedFilepaths || []) pushTerm(terms, related);
+
+    return {
+        details: [`[${diagnostic.level}]`, diagnostic.message, ...(diagnostic.relatedFilepaths || []).map((filepath) => `related=${filepath}`)],
+        kind: 'diagnostic',
+        label: diagnostic.code,
+        searchTerms: [...terms],
+        source: toSource(diagnostic.filepath, diagnostic.sourceLocation),
+    };
+};
+
+const buildManifestEntries = (manifest: TProteumManifest) => [
+    ...manifest.routes.client.map(createRouteEntry),
+    ...manifest.routes.server.map(createRouteEntry),
+    ...manifest.controllers.map(createControllerEntry),
+    ...manifest.commands.map(createCommandEntry),
+    ...manifest.services.app.map(createServiceEntry),
+    ...manifest.services.routerPlugins.map(createServiceEntry),
+    ...manifest.layouts.map(createLayoutEntry),
+    ...manifest.diagnostics.map(createDiagnosticEntry),
+];
+
+const scoreOwnerMatch = (query: string, entry: TManifestEntry) => {
+    const normalizedQuery = normalizeText(query);
+    const queryTokens = tokenize(query);
+    let score = 0;
+    const matchedOn: string[] = [];
+
+    for (const term of entry.searchTerms) {
+        if (term === normalizedQuery) {
+            score += 120;
+            matchedOn.push(term);
+            continue;
+        }
+
+        if (normalizedQuery.length >= 3 && term.includes(normalizedQuery)) {
+            score += 40;
+            matchedOn.push(term);
+        }
+    }
+
+    for (const token of queryTokens) {
+        if (entry.searchTerms.some((term) => term === token)) {
+            score += 18;
+            matchedOn.push(token);
+            continue;
+        }
+
+        if (token.length >= 3 && entry.searchTerms.some((term) => term.includes(token))) {
+            score += 8;
+            matchedOn.push(token);
+        }
+    }
+
+    if ((entry.kind === 'controller' && entry.label === query) || (entry.kind === 'route' && entry.label === query)) score += 30;
+
+    return {
+        matchedOn: [...new Set(matchedOn)],
+        score,
+    };
+};
+
+const toOwnerMatch = (entry: TManifestEntry, score: number, matchedOn: string[]): TExplainOwnerMatch => ({
+    details: entry.details,
+    kind: entry.kind,
+    label: entry.label,
+    matchedOn,
+    score,
+    source: entry.source,
+});
+
+const summarizeTraceStatus = (statusCode?: number, errorMessage?: string) => {
+    if (errorMessage) return errorMessage;
+    if (statusCode === undefined) return 'pending';
+    return String(statusCode);
+};
+
+const buildTraceItemOwner = (
+    manifest: TProteumManifest,
+    query: string,
+    kind: TTraceAttributionItem['kind'],
+    reference: string,
+    label: string,
+) => {
+    const owner = explainOwner(manifest, query).matches[0];
+    return {
+        kind,
+        label,
+        owner,
+        reference,
+    } satisfies TTraceAttributionItem;
+};
+
+const getEventQuery = (event: TTraceEvent) => {
+    const source = event.details.source;
+    if (typeof source === 'object' && source && 'entries' in source) {
+        const filepath = source.entries.filepath;
+        if (typeof filepath === 'string') return filepath;
+    }
+
+    const routePath = event.details.routePath;
+    if (typeof routePath === 'string' && routePath) return routePath;
+
+    const target = event.details.target;
+    if (typeof target === 'string' && target) return target;
+
+    const filepath = event.details.filepath;
+    if (typeof filepath === 'string' && filepath) return filepath;
+
+    return '';
+};
+
+const addSuspect = (
+    suspects: Map<string, TSuspectAccumulator>,
+    owner: TExplainOwnerMatch | undefined,
+    weight: number,
+    reason: string,
+) => {
+    if (!owner) return;
+
+    const key = `${owner.source.filepath}:${owner.source.line || 0}:${owner.source.column || 0}`;
+    const existing = suspects.get(key);
+
+    if (existing) {
+        existing.score += weight;
+        existing.reasons.add(reason);
+        return;
+    }
+
+    suspects.set(key, {
+        column: owner.source.column,
+        filepath: owner.source.filepath,
+        label: owner.label,
+        line: owner.source.line,
+        reasons: new Set([reason]),
+        score: weight,
+    });
+};
+
+/*----------------------------------
+- PUBLIC API
+----------------------------------*/
+
+export const explainOwner = (manifest: TProteumManifest, query: string): TExplainOwnerResponse => {
+    const normalizedQuery = normalizeText(query);
+    if (!normalizedQuery) return { matches: [], normalizedQuery, query };
+
+    const matches = buildManifestEntries(manifest)
+        .map((entry) => {
+            const { score, matchedOn } = scoreOwnerMatch(query, entry);
+            return score > 0 ? toOwnerMatch(entry, score, matchedOn) : undefined;
+        })
+        .filter((match): match is TExplainOwnerMatch => match !== undefined)
+        .sort((left, right) => right.score - left.score || left.kind.localeCompare(right.kind) || left.label.localeCompare(right.label))
+        .slice(0, 12);
+
+    return { matches, normalizedQuery, query };
+};
+
+export const buildTraceAttribution = (manifest: TProteumManifest, request?: TRequestTrace): TTraceAttributionResponse | undefined => {
+    if (!request) return undefined;
+
+    const primaryQuery = request.path;
+    const primary = primaryQuery
+        ? buildTraceItemOwner(manifest, primaryQuery, 'request', request.id, `${request.method} ${request.path}`)
+        : undefined;
+
+    return {
+        calls: request.calls.flatMap((call) => {
+                const query = call.path || call.label;
+                return query
+                    ? [buildTraceItemOwner(manifest, query, 'call', call.id, `${call.method || ''} ${call.path || call.label}`.trim())]
+                    : [];
+            }),
+        events: request.events.flatMap((event) => {
+                const query = getEventQuery(event);
+                return query ? [buildTraceItemOwner(manifest, query, 'event', `${event.index}`, `${event.type}`)] : [];
+            }),
+        primary,
+        sqlQueries: request.sqlQueries.flatMap((query) => {
+                const ownerQuery = query.callerPath || query.callerLabel || query.query;
+                return ownerQuery
+                    ? [buildTraceItemOwner(manifest, ownerQuery, 'sql', query.id, `${query.operation} ${query.model || query.callerPath || 'query'}`)]
+                    : [];
+            }),
+    };
+};
+
+export const buildDiagnoseResponse = ({
+    contracts,
+    doctor,
+    manifest,
+    query,
+    request,
+    serverLogs,
+}: {
+    contracts: TDoctorResponse;
+    doctor: TDoctorResponse;
+    manifest: TProteumManifest;
+    query: string;
+    request?: TRequestTrace;
+    serverLogs: TDevConsoleLogsResponse;
+}): TDiagnoseResponse => {
+    const owner = explainOwner(manifest, query);
+    const attribution = buildTraceAttribution(manifest, request);
+    const suspects = new Map<string, TSuspectAccumulator>();
+
+    addSuspect(suspects, owner.matches[0], 5, 'owner query');
+    addSuspect(suspects, attribution?.primary?.owner, 8, 'primary request');
+
+    for (const item of attribution?.events || []) addSuspect(suspects, item.owner, 2, `event:${item.label}`);
+    for (const item of attribution?.calls || []) addSuspect(suspects, item.owner, 3, `call:${item.label}`);
+    for (const item of attribution?.sqlQueries || []) addSuspect(suspects, item.owner, 1, `sql:${item.label}`);
+
+    for (const diagnostic of [...doctor.diagnostics, ...contracts.diagnostics]) {
+        const topOwner = explainOwner(manifest, diagnostic.filepath).matches[0];
+        addSuspect(suspects, topOwner, diagnostic.level === 'error' ? 4 : 2, diagnostic.code);
+    }
+
+    return {
+        attribution,
+        contracts,
+        doctor,
+        explainSummary: buildExplainSummaryItems(manifest),
+        owner,
+        query,
+        request,
+        serverLogs,
+        suspects: [...suspects.values()]
+            .sort((left, right) => right.score - left.score || left.filepath.localeCompare(right.filepath))
+            .slice(0, 12)
+            .map((suspect) => ({
+                column: suspect.column,
+                filepath: suspect.filepath,
+                label: suspect.label,
+                line: suspect.line,
+                reasons: [...suspect.reasons],
+                score: suspect.score,
+            })),
+    };
+};
+
+export const summarizeTraceForDiagnose = (request?: TRequestTrace) =>
+    !request
+        ? 'No request trace matched the diagnose query.'
+        : `${request.method} ${request.path} status=${summarizeTraceStatus(request.statusCode, request.errorMessage)} capture=${request.capture} calls=${request.calls.length} sql=${request.sqlQueries.length} events=${request.events.length}`;