memorydetective 1.13.0 → 1.15.0

package/dist/tools/analyzeLeakTimeline.js

@@ -0,0 +1,213 @@
+/**
+ * `analyzeLeakTimeline`: parses xctrace's leaks schema (the time-series
+ * instrument), distinct from `leaks(1)` CLI which is a snapshot. v1.15
+ * item E.
+ *
+ * The xctrace `leaks` instrument samples the heap periodically during
+ * recording and emits one row per leak event. Unlike leaks(1) (which
+ * gives you "what is leaked NOW") this gives you "when did the leak
+ * first appear, how did it grow, when did it peak?" Useful for fixing
+ * leaks that only fire under certain user flows.
+ *
+ * Output:
+ * - per-class first-seen-at timestamp
+ * - growth rate (instances over time)
+ * - peak instance count
+ * - aggregate event count
+ */
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { runCommand } from "../runtime/exec.js";
+import { fetchDiscoveredSchemas } from "../parsers/schemaDiscovery.js";
+import { parseXctraceXml, asNumber, asFormatted, } from "../parsers/xctraceXml.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
+export const analyzeLeakTimelineSchema = z.object({
+    tracePath: z
+        .string()
+        .min(1)
+        .describe("Absolute path to a `.trace` bundle recorded with a Leaks template."),
+    topN: z
+        .number()
+        .int()
+        .positive()
+        .default(10)
+        .describe("Return the top N leaked classes ranked by peak instance count (default 10)."),
+    outputFormat: outputFormatField,
+});
+function pickNumber(row, keys) {
+    for (const k of keys) {
+        const v = asNumber(row[k]);
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+function pickString(row, keys) {
+    for (const k of keys) {
+        const v = asFormatted(row[k]);
+        if (v && v.trim().length > 0)
+            return v.trim();
+    }
+    return undefined;
+}
+/** Pure: turn the leaks XML into the timeline analysis. */
+export function analyzeLeakTimelineFromXml(xml, tracePath, topN = 10) {
+    const tables = parseXctraceXml(xml);
+    // xctrace's Leaks instrument typically labels the schema "leaks" or
+    // "leak-events". Match conservatively against both.
+    const table = tables.find((t) => /^leaks?$/i.test(t.schema) || /leak-events?/i.test(t.schema));
+    if (!table) {
+        return {
+            ok: true,
+            tracePath,
+            totals: { rows: 0, classes: 0 },
+            topClasses: [],
+            diagnosis: "No leaks table found in the trace.",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "leak-events",
+                    status: "not_present",
+                    reason: "Schema absent from the trace TOC.",
+                },
+            ],
+        };
+    }
+    const events = [];
+    for (const row of table.rows) {
+        const startNs = pickNumber(row, ["time", "event-time", "start", "sample-time"]) ?? 0;
+        const className = pickString(row, [
+            "class",
+            "class-name",
+            "type",
+            "type-name",
+            "leak-type",
+        ]) ?? "";
+        if (!className)
+            continue;
+        const cumulativeCount = pickNumber(row, [
+            "count",
+            "cumulative-count",
+            "instances",
+        ]);
+        const totalBytes = pickNumber(row, [
+            "bytes",
+            "size",
+            "total-bytes",
+            "leaked-bytes",
+        ]);
+        events.push({
+            startNs,
+            ...(asFormatted(row.time) ? { startFmt: asFormatted(row.time) } : {}),
+            className,
+            ...(cumulativeCount != null ? { cumulativeCount } : {}),
+            ...(totalBytes != null ? { totalBytes } : {}),
+        });
+    }
+    // Group events by class. Track first-seen-at, peakCount, peakBytes,
+    // event count per class.
+    const byClass = new Map();
+    for (const ev of events) {
+        const cur = byClass.get(ev.className) ??
+            {
+                className: ev.className,
+                firstSeenAtNs: ev.startNs,
+                firstSeenAtFmt: ev.startFmt,
+                peakCount: 0,
+                peakBytes: 0,
+                eventCount: 0,
+            };
+        if (ev.startNs < cur.firstSeenAtNs) {
+            cur.firstSeenAtNs = ev.startNs;
+            if (ev.startFmt)
+                cur.firstSeenAtFmt = ev.startFmt;
+        }
+        if (ev.cumulativeCount != null && ev.cumulativeCount > cur.peakCount) {
+            cur.peakCount = ev.cumulativeCount;
+        }
+        if (ev.totalBytes != null && ev.totalBytes > cur.peakBytes) {
+            cur.peakBytes = ev.totalBytes;
+        }
+        cur.eventCount += 1;
+        byClass.set(ev.className, cur);
+    }
+    const topClasses = Array.from(byClass.values())
+        .sort((a, b) => {
+        const peakDiff = b.peakCount - a.peakCount;
+        if (peakDiff !== 0)
+            return peakDiff;
+        return b.eventCount - a.eventCount;
+    })
+        .slice(0, topN);
+    const lastEventNs = events.reduce((max, e) => Math.max(max, e.startNs), 0);
+    return {
+        ok: true,
+        tracePath,
+        totals: {
+            rows: events.length,
+            classes: byClass.size,
+            ...(lastEventNs > 0 ? { lastEventNs } : {}),
+        },
+        topClasses,
+        diagnosis: buildDiagnosis(events.length, byClass.size, topClasses),
+        status: "available",
+        supportStatus: [
+            {
+                kind: "leak-events",
+                status: "available",
+                sourceSchemas: ["leaks"],
+            },
+        ],
+    };
+}
+function buildDiagnosis(rows, classes, topClasses) {
+    if (rows === 0) {
+        return "No leak events in the recording.";
+    }
+    const parts = [];
+    parts.push(`${rows} leak event${rows === 1 ? "" : "s"} across ${classes} class${classes === 1 ? "" : "es"}.`);
+    if (topClasses.length > 0) {
+        const top = topClasses[0];
+        parts.push(`Top leaked: \`${top.className}\` (peak ${top.peakCount} instances, first seen at ${(top.firstSeenAtNs / 1e9).toFixed(2)}s).`);
+    }
+    if (classes >= 5) {
+        parts.push("Multiple class signatures leaking. Suggests a shared cause (e.g. notification observer not removed) rather than a single one-off.");
+    }
+    return parts.join(" ");
+}
+export async function analyzeLeakTimeline(input) {
+    const tracePath = resolvePath(input.tracePath);
+    if (!existsSync(tracePath)) {
+        throw new Error(`Trace bundle not found: ${tracePath}`);
+    }
+    const { leaks: schemaName } = await fetchDiscoveredSchemas(runCommand, tracePath, ["leaks"]);
+    const result = await runCommand("xcrun", [
+        "xctrace",
+        "export",
+        "--input",
+        tracePath,
+        "--xpath",
+        `/trace-toc/run/data/table[@schema="${schemaName}"]`,
+    ], { timeoutMs: 5 * 60_000 });
+    if (result.code !== 0) {
+        return {
+            ok: true,
+            tracePath,
+            totals: { rows: 0, classes: 0 },
+            topClasses: [],
+            diagnosis: "Leaks schema not exportable from this trace (likely recorded with a non-Leaks template).",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "leak-events",
+                    status: "not_exportable",
+                    reason: "xctrace export failed for the leaks schema family.",
+                    sourceSchemas: [schemaName],
+                },
+            ],
+        };
+    }
+    return analyzeLeakTimelineFromXml(result.stdout, tracePath, input.topN ?? 10);
+}
+//# sourceMappingURL=analyzeLeakTimeline.js.map

package/dist/tools/analyzeLeakTimeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeLeakTimeline.js","sourceRoot":"","sources":["../../src/tools/analyzeLeakTimeline.ts"],"names":[],"mappings":"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"}

package/dist/tools/analyzeMemoryFootprint.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `analyzeMemoryFootprint`: parses xctrace's memory-footprint schema. v1.15 item C.
+ *
+ * Distinct from analyzeAllocations: that tool surfaces category-level
+ * cumulative allocation bytes ("which classes are bloated?"). This tool
+ * surfaces process-level VM state ("how much RAM is the OS giving us
+ * right now, and where is it going?"): resident memory, dirty memory,
+ * VM regions, and the timeline of pressure events.
+ *
+ * The "why is my app getting OOM-killed?" investigation. iOS jetsam
+ * decisions are made based on dirty + footprint, not cumulative malloc.
+ */
+import { z } from "zod";
+import type { DataStatus, SupportStatus } from "../types.js";
+export declare const analyzeMemoryFootprintSchema: z.ZodObject<{
+    tracePath: z.ZodString;
+    topN: z.ZodDefault<z.ZodNumber>;
+    outputFormat: z.ZodOptional<z.ZodEnum<["markdown", "json", "both", "verify-fix-table"]>>;
+}, "strip", z.ZodTypeAny, {
+    tracePath: string;
+    topN: number;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
+}, {
+    tracePath: string;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
+    topN?: number | undefined;
+}>;
+export type AnalyzeMemoryFootprintInput = z.infer<typeof analyzeMemoryFootprintSchema>;
+export interface MemoryFootprintSample {
+    startNs: number;
+    startFmt?: string;
+    /** Resident memory in bytes (RAM the process is using right now). */
+    residentBytes?: number;
+    /** Dirty memory in bytes (the OOM-kill discriminator on iOS). */
+    dirtyBytes?: number;
+    /** Compressed memory in bytes. */
+    compressedBytes?: number;
+    /** Virtual memory in bytes (address-space, not necessarily resident). */
+    virtualBytes?: number;
+    /** Optional sample-level label (e.g. "memory-warning", "background-event"). */
+    label?: string;
+}
+export interface AnalyzeMemoryFootprintResult {
+    ok: boolean;
+    tracePath: string;
+    totals: {
+        rows: number;
+        /** Peak resident bytes seen across all samples. */
+        peakResidentBytes: number;
+        /** Peak dirty bytes seen across all samples. */
+        peakDirtyBytes: number;
+        /** Average resident bytes across all samples. */
+        averageResidentBytes: number;
+        /** Time of peak resident as ns offset from recording start. */
+        peakResidentAtNs?: number;
+    };
+    /** Top N samples ranked by resident bytes desc. */
+    topByResident: MemoryFootprintSample[];
+    diagnosis: string;
+    /** @deprecated v1.14 item I. Use `supportStatus[]`. */
+    status: DataStatus;
+    /** v1.14+. Unified per-area status. */
+    supportStatus: SupportStatus[];
+}
+/**
+ * Format a byte count as human-friendly KB/MB. v1.15. Exported for
+ * the diagnosis text and downstream callers.
+ */
+export declare function formatBytes(n: number | undefined): string;
+/** Pure: turn the memory-footprint XML into the analyzed result. */
+export declare function analyzeMemoryFootprintFromXml(xml: string, tracePath: string, topN?: number): AnalyzeMemoryFootprintResult;
+export declare function analyzeMemoryFootprint(input: AnalyzeMemoryFootprintInput): Promise<AnalyzeMemoryFootprintResult>;

package/dist/tools/analyzeMemoryFootprint.js

@@ -0,0 +1,234 @@
+/**
+ * `analyzeMemoryFootprint`: parses xctrace's memory-footprint schema. v1.15 item C.
+ *
+ * Distinct from analyzeAllocations: that tool surfaces category-level
+ * cumulative allocation bytes ("which classes are bloated?"). This tool
+ * surfaces process-level VM state ("how much RAM is the OS giving us
+ * right now, and where is it going?"): resident memory, dirty memory,
+ * VM regions, and the timeline of pressure events.
+ *
+ * The "why is my app getting OOM-killed?" investigation. iOS jetsam
+ * decisions are made based on dirty + footprint, not cumulative malloc.
+ */
+import { z } from "zod";
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { runCommand } from "../runtime/exec.js";
+import { fetchDiscoveredSchemas } from "../parsers/schemaDiscovery.js";
+import { parseXctraceXml, asNumber, asFormatted, } from "../parsers/xctraceXml.js";
+import { outputFormatField } from "../runtime/responseFormatter.js";
+export const analyzeMemoryFootprintSchema = z.object({
+    tracePath: z
+        .string()
+        .min(1)
+        .describe("Absolute path to a `.trace` bundle recorded with an Allocations or System Trace template that includes the memory-footprint instrument."),
+    topN: z
+        .number()
+        .int()
+        .positive()
+        .default(10)
+        .describe("Return the top N memory snapshots ranked by resident bytes (default 10)."),
+    outputFormat: outputFormatField,
+});
+function pickNumber(row, keys) {
+    for (const k of keys) {
+        const v = asNumber(row[k]);
+        if (typeof v === "number" && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+function pickString(row, keys) {
+    for (const k of keys) {
+        const v = asFormatted(row[k]);
+        if (v && v.trim().length > 0)
+            return v.trim();
+    }
+    return undefined;
+}
+/**
+ * Format a byte count as human-friendly KB/MB. v1.15. Exported for
+ * the diagnosis text and downstream callers.
+ */
+export function formatBytes(n) {
+    if (n == null || !Number.isFinite(n))
+        return "n/a";
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+/** Pure: turn the memory-footprint XML into the analyzed result. */
+export function analyzeMemoryFootprintFromXml(xml, tracePath, topN = 10) {
+    const tables = parseXctraceXml(xml);
+    // The memory-footprint schema may appear under different names
+    // depending on the template (memory-footprint, resident-memory, etc).
+    // Match conservatively against the canonical name first, then any
+    // schema whose name matches the SCHEMA_FAMILIES.memory patterns
+    // already validated in schemaDiscovery.
+    const table = tables.find((t) => t.schema === "memory-footprint" ||
+        /memory-footprint/i.test(t.schema) ||
+        /resident-memory/i.test(t.schema));
+    if (!table) {
+        return {
+            ok: true,
+            tracePath,
+            totals: {
+                rows: 0,
+                peakResidentBytes: 0,
+                peakDirtyBytes: 0,
+                averageResidentBytes: 0,
+            },
+            topByResident: [],
+            diagnosis: "No memory-footprint table found in the trace.",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "memory-footprint",
+                    status: "not_present",
+                    reason: "Schema absent from the trace TOC.",
+                },
+            ],
+        };
+    }
+    const samples = [];
+    for (const row of table.rows) {
+        const startNs = pickNumber(row, ["time", "sample-time", "event-time", "start"]) ?? 0;
+        const residentBytes = pickNumber(row, [
+            "resident",
+            "resident-bytes",
+            "resident-memory",
+            "phys",
+            "phys-footprint",
+        ]);
+        const dirtyBytes = pickNumber(row, [
+            "dirty",
+            "dirty-bytes",
+            "dirty-memory",
+            "private-dirty",
+        ]);
+        const compressedBytes = pickNumber(row, [
+            "compressed",
+            "compressed-bytes",
+            "compressed-memory",
+        ]);
+        const virtualBytes = pickNumber(row, [
+            "virtual",
+            "virtual-bytes",
+            "vm-size",
+            "vsize",
+        ]);
+        const label = pickString(row, ["label", "event", "event-type", "category"]);
+        samples.push({
+            startNs,
+            ...(asFormatted(row.time) ? { startFmt: asFormatted(row.time) } : {}),
+            ...(residentBytes != null ? { residentBytes } : {}),
+            ...(dirtyBytes != null ? { dirtyBytes } : {}),
+            ...(compressedBytes != null ? { compressedBytes } : {}),
+            ...(virtualBytes != null ? { virtualBytes } : {}),
+            ...(label ? { label } : {}),
+        });
+    }
+    const residents = samples
+        .map((s) => s.residentBytes)
+        .filter((v) => v != null);
+    const dirties = samples
+        .map((s) => s.dirtyBytes)
+        .filter((v) => v != null);
+    const peakResidentBytes = residents.length > 0 ? Math.max(...residents) : 0;
+    const peakDirtyBytes = dirties.length > 0 ? Math.max(...dirties) : 0;
+    const averageResidentBytes = residents.length > 0
+        ? residents.reduce((a, b) => a + b, 0) / residents.length
+        : 0;
+    const peakSample = samples.find((s) => s.residentBytes === peakResidentBytes);
+    const peakResidentAtNs = peakSample?.startNs;
+    const topByResident = [...samples]
+        .sort((a, b) => (b.residentBytes ?? 0) - (a.residentBytes ?? 0))
+        .slice(0, topN);
+    return {
+        ok: true,
+        tracePath,
+        totals: {
+            rows: samples.length,
+            peakResidentBytes,
+            peakDirtyBytes,
+            averageResidentBytes,
+            ...(peakResidentAtNs != null ? { peakResidentAtNs } : {}),
+        },
+        topByResident,
+        diagnosis: buildDiagnosis(samples.length, peakResidentBytes, peakDirtyBytes),
+        status: "available",
+        supportStatus: [
+            {
+                // The SupportStatusKind enum doesn't have memory-footprint yet;
+                // tagging as potential-hangs is wrong. We extend the enum in a
+                // follow-up; for now use a generic kind and put the real schema
+                // name in sourceSchemas so callers branch on that.
+                kind: "memory-footprint",
+                status: "available",
+                sourceSchemas: ["memory-footprint"],
+            },
+        ],
+    };
+}
+function buildDiagnosis(rows, peakResidentBytes, peakDirtyBytes) {
+    if (rows === 0) {
+        return "No memory-footprint samples in the recording.";
+    }
+    const parts = [];
+    parts.push(`${rows} memory snapshots.`);
+    if (peakResidentBytes > 0) {
+        parts.push(`Peak resident: ${formatBytes(peakResidentBytes)}.`);
+    }
+    if (peakDirtyBytes > 0) {
+        parts.push(`Peak dirty: ${formatBytes(peakDirtyBytes)}.`);
+    }
+    // Apple's jetsam thresholds vary by device class but ~200MB dirty is
+    // a reasonable "you're getting close to OOM" line for most apps.
+    if (peakDirtyBytes > 200 * 1024 * 1024) {
+        parts.push("Peak dirty memory above 200 MB. Approaching jetsam territory on smaller devices.");
+    }
+    return parts.join(" ");
+}
+export async function analyzeMemoryFootprint(input) {
+    const tracePath = resolvePath(input.tracePath);
+    if (!existsSync(tracePath)) {
+        throw new Error(`Trace bundle not found: ${tracePath}`);
+    }
+    const { memory: schemaName } = await fetchDiscoveredSchemas(runCommand, tracePath, ["memory"]);
+    const result = await runCommand("xcrun", [
+        "xctrace",
+        "export",
+        "--input",
+        tracePath,
+        "--xpath",
+        `/trace-toc/run/data/table[@schema="${schemaName}"]`,
+    ], { timeoutMs: 5 * 60_000 });
+    if (result.code !== 0) {
+        return {
+            ok: true,
+            tracePath,
+            totals: {
+                rows: 0,
+                peakResidentBytes: 0,
+                peakDirtyBytes: 0,
+                averageResidentBytes: 0,
+            },
+            topByResident: [],
+            diagnosis: "Memory-footprint schema not exportable from this trace (likely recorded with a non-Allocations / non-System-Trace template).",
+            status: "not_present",
+            supportStatus: [
+                {
+                    kind: "potential-hangs",
+                    status: "not_exportable",
+                    reason: "xctrace export failed for the memory schema family.",
+                },
+            ],
+        };
+    }
+    return analyzeMemoryFootprintFromXml(result.stdout, tracePath, input.topN ?? 10);
+}
+//# sourceMappingURL=analyzeMemoryFootprint.js.map

package/dist/tools/analyzeMemoryFootprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzeMemoryFootprint.js","sourceRoot":"","sources":["../../src/tools/analyzeMemoryFootprint.ts"],"names":[],"mappings":"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"}

package/dist/tools/analyzeNetworkActivity.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `analyzeNetworkActivity`: parses xctrace's network-connections schema
+ * from a `.trace` recorded with the Network Profile template. v1.14 item A.
+ *
+ * "The network is slow" / "my SDK is chatty" / "slow launch because of
+ * one API call" are top-3 iOS perf complaints. Pre-v1.14 we had zero
+ * coverage of the network family. XcodeTraceMCP's regex map listed it
+ * as one of their five instrument families. This analyzer closes the
+ * gap with the same shape as analyzeHangs / analyzeAnimationHitches:
+ *
+ * - Bytes-in/out, duration, status-code, and URL/host extracted per
+ *   connection.
+ * - Aggregates: total bytes, slowest response, average response, count
+ *   per HTTP status bucket.
+ * - Top-N by duration (the "which calls blocked the user?" view) and
+ *   top-N by bytes (the "which calls are bloating my budget?" view).
+ * - Per-host aggregates surfacing chatty SDKs without manually grouping.
+ *
+ * Resilient to column-name drift across xctrace versions: each field
+ * is looked up under multiple plausible mnemonics, falling back to the
+ * one that yields data.
+ */
+import { z } from "zod";
+import type { DataStatus, SupportStatus } from "../types.js";
+export declare const analyzeNetworkActivitySchema: z.ZodObject<{
+    tracePath: z.ZodString;
+    topN: z.ZodDefault<z.ZodNumber>;
+    minBytes: z.ZodDefault<z.ZodNumber>;
+    outputFormat: z.ZodOptional<z.ZodEnum<["markdown", "json", "both", "verify-fix-table"]>>;
+}, "strip", z.ZodTypeAny, {
+    tracePath: string;
+    topN: number;
+    minBytes: number;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
+}, {
+    tracePath: string;
+    outputFormat?: "markdown" | "json" | "both" | "verify-fix-table" | undefined;
+    topN?: number | undefined;
+    minBytes?: number | undefined;
+}>;
+export type AnalyzeNetworkActivityInput = z.infer<typeof analyzeNetworkActivitySchema>;
+export interface NetworkConnectionEntry {
+    /** Start timestamp in nanoseconds since recording start. */
+    startNs: number;
+    startFmt?: string;
+    /** Response/transaction duration in nanoseconds when available. */
+    durationNs?: number;
+    durationMs?: number;
+    durationFmt?: string;
+    /** URL or hostname (whichever the trace exposed). */
+    url?: string;
+    /** Host portion of the URL, when parseable. */
+    host?: string;
+    /** HTTP method (GET, POST, etc.) when present. */
+    method?: string;
+    /** HTTP response status code. */
+    statusCode?: number;
+    /** Bytes received from the server (response body + headers). */
+    bytesIn?: number;
+    /** Bytes sent to the server (request body + headers). */
+    bytesOut?: number;
+}
+export interface NetworkHostAggregate {
+    host: string;
+    count: number;
+    bytesIn: number;
+    bytesOut: number;
+    longestMs: number;
+}
+export interface AnalyzeNetworkActivityResult {
+    ok: boolean;
+    tracePath: string;
+    totals: {
+        rows: number;
+        totalBytesIn: number;
+        totalBytesOut: number;
+        longestMs: number;
+        averageMs: number;
+        /** Status-code bucket counts. Example: `{ "2xx": 47, "4xx": 3, "5xx": 1, "n/a": 12 }`. */
+        statusBuckets: Record<string, number>;
+    };
+    /** Top N connections ranked by `durationMs` desc. */
+    topByDuration: NetworkConnectionEntry[];
+    /** Top N connections ranked by `bytesIn + bytesOut` desc. */
+    topByBytes: NetworkConnectionEntry[];
+    /** Per-host aggregates, ranked by request count desc. */
+    byHost: NetworkHostAggregate[];
+    diagnosis: string;
+    /** @deprecated v1.14 item I. Use `supportStatus[]` instead. */
+    status: DataStatus;
+    /** v1.14+. Unified per-area status. See {@link SupportStatus}. */
+    supportStatus: SupportStatus[];
+}
+/** Extract a host string from a URL-or-host value. Falls back to the
+ *  raw input when it does not look like a URL (already a host). */
+export declare function extractHost(urlOrHost: string | undefined): string | undefined;
+/** Pure: turn the network-connections XML into the analyzed result. */
+export declare function analyzeNetworkActivityFromXml(xml: string, tracePath: string, topN?: number, minBytes?: number): AnalyzeNetworkActivityResult;
+export declare function analyzeNetworkActivity(input: AnalyzeNetworkActivityInput): Promise<AnalyzeNetworkActivityResult>;