@memlab/mcp-server 2.18.1 → 2.86.0

package/dist/tools/collection-diff.js

@@ -0,0 +1,343 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import fs from 'fs';
+import memlabCore from '@memlab/core';
+import { z } from 'zod';
+import { errorResult, formatNumber, markdownTable, pathsHeader, toolResult, } from '../utils.js';
+import { countEntries } from './collection-trend.js';
+import { resolveLadderPaths } from './ladder.js';
+import { resolveMaxFileSizeMB, resolveSnapshotPath } from './load-snapshot.js';
+const { utils: memlabUtils } = memlabCore;
+/**
+ * Class names that carry no information as an owner label. A signature built on
+ * one of these is not distinguishable from thousands of others, so the walk
+ * keeps climbing to find something nameable.
+ */
+const GENERIC_OWNER_NAMES = new Set([
+    '',
+    'Object',
+    'Array',
+    'Map',
+    'Set',
+    'WeakMap',
+    'WeakSet',
+    '(object elements)',
+    '(object properties)',
+]);
+/** JS-level collections a caller can actually act on. */
+const COLLECTION_CLASS_NAMES = new Set([
+    'Map',
+    'Set',
+    'WeakMap',
+    'WeakSet',
+    'Array',
+]);
+const MAX_OWNER_HOPS = 4;
+function isGenericOwner(name) {
+    if (GENERIC_OWNER_NAMES.has(name))
+        return true;
+    // `system / Context / scope @805823` — the scope id is per-capture, so the
+    // name is both generic AND unstable. Collapsed to `<context>` below.
+    if (name.startsWith('system / Context'))
+        return true;
+    if (name.startsWith('system /'))
+        return true;
+    return false;
+}
+function edgeLabel(edge) {
+    const raw = String(edge.name_or_index);
+    if (raw === '' || /^\d+$/.test(raw))
+        return null;
+    if (raw === '__proto__' || raw === 'map' || raw === 'elements')
+        return null;
+    return raw;
+}
+/**
+ * A per-capture-stable name for one collection, in the SAME `<Owner>.<property>`
+ * form `memlab_collection_trend` takes as a locator.
+ *
+ * That shared shape is the point of this tool: discovery hands you a locator you
+ * can paste straight into the trend tool to confirm and to track a fix, instead
+ * of a node id that means nothing in the next capture.
+ *
+ * Node ids, array indices and V8 scope numbers are all per-capture, so none of
+ * them can appear in the signature. The walk climbs referrers (not the dominator
+ * tree — this runs on a LIGHT parse with no dominators) until it finds a class
+ * name worth printing, and falls back to `<context>` for a module-scope closure
+ * binding, which is where most module singletons live.
+ */
+export function collectionSignature(node) {
+    let binding = null;
+    let owner = null;
+    // Prefer a `property` binding, then a closure `context` binding; both name the
+    // field the collection is stored in, which is what a reader needs.
+    for (const pass of ['property', 'context', 'any']) {
+        for (const edge of node.referrers) {
+            if (pass !== 'any' && edge.type !== pass)
+                continue;
+            if (edge.type === 'hidden' || edge.type === 'internal')
+                continue;
+            const label = edgeLabel(edge);
+            if (label == null)
+                continue;
+            const from = edge.fromNode;
+            if (from == null || from.id <= 3)
+                continue;
+            binding = label;
+            owner = from;
+            break;
+        }
+        if (binding != null)
+            break;
+    }
+    if (binding == null || owner == null)
+        return null;
+    // Climb until the owner has a name worth printing.
+    let hops = 0;
+    const prefixParts = [];
+    let cur = owner;
+    while (cur != null && hops < MAX_OWNER_HOPS && isGenericOwner(cur.name)) {
+        let next = null;
+        let nextLabel = null;
+        for (const edge of cur.referrers) {
+            if (edge.type === 'hidden' || edge.type === 'internal')
+                continue;
+            const label = edgeLabel(edge);
+            if (label == null)
+                continue;
+            const from = edge.fromNode ?? null;
+            if (from == null || from.id <= 3)
+                continue;
+            next = from;
+            nextLabel = label;
+            break;
+        }
+        if (next == null)
+            break;
+        if (nextLabel != null)
+            prefixParts.unshift(nextLabel);
+        cur = next;
+        hops++;
+    }
+    let ownerLabel;
+    if (cur == null) {
+        ownerLabel = 'Object';
+    }
+    else if (cur.name.startsWith('system / Context')) {
+        ownerLabel = '<context>';
+    }
+    else if (isGenericOwner(cur.name)) {
+        ownerLabel = cur.name.length > 0 ? cur.name : 'Object';
+    }
+    else {
+        ownerLabel = cur.name;
+    }
+    return [ownerLabel, ...prefixParts, binding].join('.');
+}
+/**
+ * Census every JS collection in one snapshot, keyed by signature.
+ *
+ * Deliberately does NOT filter by size. The whole point is to catch the
+ * collection that is small now and unbounded later: one of the three
+ * never-drained telemetry stores this tool was written for held 2 entries at the
+ * baseline rung and 1,260 at the last one, so any size floor would have hidden
+ * it. Growth is the filter, and growth needs the ladder.
+ */
+export function censusCollections(snapshot) {
+    const out = new Map();
+    snapshot.nodes.forEach((node) => {
+        if (node.id <= 3)
+            return;
+        if (!COLLECTION_CLASS_NAMES.has(node.name))
+            return;
+        const n = countEntries(node);
+        if (n == null || n === 0)
+            return;
+        const sig = collectionSignature(node);
+        if (sig == null)
+            return;
+        let s = out.get(sig);
+        if (!s) {
+            s = { instances: 0, entries: 0, maxEntries: 0, kinds: new Set() };
+            out.set(sig, s);
+        }
+        s.instances++;
+        s.entries += n;
+        if (n > s.maxEntries)
+            s.maxEntries = n;
+        s.kinds.add(node.name);
+    });
+    return out;
+}
+function buildRows(perRung, minGrowth) {
+    const sigs = new Set();
+    for (const m of perRung)
+        for (const k of m.keys())
+            sigs.add(k);
+    const rows = [];
+    for (const sig of sigs) {
+        const series = perRung.map(m => m.get(sig)?.entries ?? 0);
+        const instances = perRung.map(m => m.get(sig)?.instances ?? 0);
+        const delta = series[series.length - 1] - series[0];
+        if (delta < minGrowth)
+            continue;
+        let monotonic = true;
+        for (let i = 1; i < series.length; i++) {
+            if (series[i] <= series[i - 1])
+                monotonic = false;
+        }
+        const kinds = new Set();
+        for (const m of perRung) {
+            const s = m.get(sig);
+            if (s)
+                for (const k of s.kinds)
+                    kinds.add(k);
+        }
+        rows.push({
+            sig,
+            kind: [...kinds].sort().join('/'),
+            series,
+            instances,
+            maxEntries: Math.max(...perRung.map(m => m.get(sig)?.maxEntries ?? 0)),
+            delta,
+            monotonic,
+        });
+    }
+    rows.sort((a, b) => {
+        if (a.monotonic !== b.monotonic)
+            return a.monotonic ? -1 : 1;
+        return b.delta - a.delta;
+    });
+    return rows;
+}
+export function registerCollectionDiff(server) {
+    server.tool('memlab_collection_diff', 'Find WHICH collections grew across a snapshot ladder, WITHOUT being told their names. Censuses every Map/Set/WeakMap/WeakSet/Array on every rung, keys each by a per-capture-STABLE `<Owner>.<property>` signature, and diffs the entry counts. ' +
+        'This is the discovery half of memlab_collection_trend, which is excellent but requires a locator you must already know — so every accumulating collection had to be found first by hand-tracing a retainer path, and the ones nobody thought to trace were never found at all. ' +
+        'It is also the answer to the case the single-snapshot tools structurally cannot see: memlab_cache_analysis and memlab_growth_signals rank by SIZE on one rung, so they surface big-and-static collections and miss the small-but-unbounded one. This tool applies NO size floor — growth is the filter — because the store that matters most may hold 2 entries at the baseline. ' +
+        'The signatures it emits are valid memlab_collection_trend locators: confirm a candidate, and later verify a fix, by pasting one straight in. ' +
+        'Loads each rung transiently in LIGHT mode (one graph resident at a time), so it is safe on ladders too large to hold in memory at once.', {
+        paths: z
+            .array(z.string())
+            .min(1)
+            .describe('Ordered snapshot paths, OLDEST FIRST (>=2). A single ["ladder:<name>"] element expands to a saved ladder (see memlab_ladder).'),
+        cycles: z
+            .number()
+            .optional()
+            .describe('Interaction cycles driven between the FIRST and LAST rung. When given, a Δ/cycle column is reported — the per-cycle rate is what says whether a collection scales with interaction.'),
+        min_growth: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Only report collections whose total entry count grew by at least this across the ladder (default 20). This is a GROWTH floor, not a size floor — a collection that went 2 -> 1,260 is reported, one that sits flat at 9,356 is not.'),
+        limit: z
+            .number()
+            .optional()
+            .default(30)
+            .describe('Maximum number of collections to report (default 30).'),
+        monotonic_only: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Only report collections that grew at EVERY rung (default false: grew-net collections are included and flagged).'),
+        max_file_size_mb: z
+            .number()
+            .optional()
+            .describe('Per-file size limit override (MB).'),
+    }, async ({ paths, cycles, min_growth, limit, monotonic_only, max_file_size_mb, }) => {
+        try {
+            const { paths: resolved } = resolveLadderPaths(paths);
+            if (resolved.length < 2) {
+                return errorResult('memlab_collection_diff needs at least 2 snapshots — it diffs collection sizes across a ladder. For a single snapshot use memlab_cache_analysis or memlab_growth_signals.');
+            }
+            const labels = [];
+            const perRung = [];
+            for (const p of resolved) {
+                let local;
+                let fetchedFrom = null;
+                try {
+                    const r = resolveSnapshotPath(p);
+                    local = r.localPath;
+                    fetchedFrom = r.fetchedFrom;
+                }
+                catch (e) {
+                    return errorResult(`Failed to resolve "${p}": ${e instanceof Error ? e.message : String(e)}`);
+                }
+                if (!fs.existsSync(local)) {
+                    return errorResult(`File not found: ${local}`);
+                }
+                const sizeMB = fs.statSync(local).size / (1024 * 1024);
+                const cap = resolveMaxFileSizeMB(max_file_size_mb, fetchedFrom != null);
+                if (sizeMB > cap) {
+                    return errorResult(`${p} is ${sizeMB.toFixed(0)} MB — exceeds the ${cap} MB per-file safety limit. Raise it with max_file_size_mb: ${Math.ceil(sizeMB + 100)}.`);
+                }
+                const snapshot = await memlabUtils.getSnapshotFromFile(local, {
+                    buildNodeIdIndex: true,
+                    verbose: false,
+                });
+                labels.push(fetchedFrom ?? p.replace(/^.*\//, ''));
+                perRung.push(censusCollections(snapshot));
+            }
+            let rows = buildRows(perRung, min_growth);
+            if (monotonic_only)
+                rows = rows.filter(r => r.monotonic);
+            const shown = rows.slice(0, limit);
+            const perCycle = cycles != null && cycles > 0;
+            const lines = [
+                `## Collection diff across ${resolved.length} rung(s)`,
+                '',
+            ];
+            if (shown.length === 0) {
+                lines.push(`No collection grew by ${formatNumber(min_growth)} or more entries across this ladder.`, '', '_That is a real negative for unbounded-collection growth specifically — it does not cover detached DOM, listener records, string accumulation or retained-size growth with a flat entry count. Lower `min_growth` to see smaller movers._');
+                return toolResult(lines.join('\n'), pathsHeader(labels));
+            }
+            const headers = [
+                'Collection (usable as a collection_trend locator)',
+                'Kind',
+                ...labels.map((_, i) => `r${i}`),
+                'Δ',
+                ...(perCycle ? ['Δ/cycle'] : []),
+                'Instances',
+                'Largest',
+                'Trend',
+            ];
+            const right = new Set();
+            for (let i = 2; i < headers.length - 1; i++)
+                right.add(i);
+            const table = shown.map(r => [
+                r.sig.length > 52 ? r.sig.slice(0, 49) + '…' : r.sig,
+                r.kind,
+                ...r.series.map(v => formatNumber(v)),
+                `+${formatNumber(r.delta)}`,
+                ...(perCycle ? [(r.delta / cycles).toFixed(2)] : []),
+                `${formatNumber(r.instances[0])} → ${formatNumber(r.instances[r.instances.length - 1])}`,
+                formatNumber(r.maxEntries),
+                r.monotonic ? '↑ every rung' : 'grew net',
+            ]);
+            lines.push(markdownTable(headers, table, right));
+            const mono = shown.filter(r => r.monotonic);
+            lines.push('', `**${formatNumber(mono.length)} of ${formatNumber(shown.length)} shown grew at EVERY rung** — monotonic growth under a repeated interaction is the signature of an unbounded collection.` +
+                (rows.length > shown.length
+                    ? ` ${formatNumber(rows.length - shown.length)} more above the growth floor were not shown (raise \`limit\`).`
+                    : ''));
+            if (mono.length > 0) {
+                lines.push('', '**Next:** confirm one with the trend tool, which measures the same collection per rung and reports owners separately from entries:', '```', `memlab_collection_trend({paths: [...], locators: [${mono
+                    .slice(0, 4)
+                    .map(r => `"${r.sig}"`)
+                    .join(', ')}]${perCycle ? `, cycles: ${cycles}` : ''}})`, '```', 'Then `memlab_retainer_trace` the owner to name what holds it, and check whether the entries are distinct rather than one object re-added.');
+            }
+            lines.push('', '_Instances is the count of DISTINCT collections sharing a signature. When instances grow but the largest single collection does not, the OWNERS are accumulating, not the collection — a different fix (stop minting owners) from bounding one container._', '_Signatures are structural, not identities: two unrelated collections bound to the same-named field of the same-named class share a row. The `Instances` column is what exposes that._');
+            return toolResult(lines.join('\n'), pathsHeader(labels));
+        }
+        catch (error) {
+            return errorResult(`Failed to diff collections: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+//# sourceMappingURL=collection-diff.js.map

package/dist/tools/collection-diff.js.map

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

package/dist/tools/collection-trend.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { IHeapNode, IHeapSnapshot } from '@memlab/core';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * A locator names a collection by the OWNER CLASS and the property path that
+ * reaches it — `LoggerImpl.logs`, `Store.cache.entries`.
+ *
+ * Deliberately not a node id: ids are per-capture, so an id-keyed ladder query
+ * silently tracks a different object (or nothing) at every rung, which is the
+ * failure this tool exists to remove. Matching by class + path is what makes a
+ * collection comparable across snapshots at all.
+ */
+export interface Locator {
+    ownerClass: string;
+    path: string[];
+    raw: string;
+}
+export declare function parseLocator(spec: string): Locator;
+export declare function resolvePath(owner: IHeapNode, path: string[]): IHeapNode | null;
+/**
+ * Number of entries held by a collection node, by V8 kind.
+ *
+ * Returns null when the node is not a container — reported as "not a
+ * collection" rather than as 0 entries, because those two read identically in a
+ * table and mean opposite things (an empty cache vs a mistyped locator).
+ */
+export declare function countEntries(node: IHeapNode): number | null;
+export interface LocatorMeasurement {
+    owners: number;
+    resolved: number;
+    entries: number;
+    maxEntries: number;
+    nonCollection: boolean;
+}
+export declare function measureLocators(snapshot: IHeapSnapshot, locators: Locator[]): Map<string, LocatorMeasurement>;
+/**
+ * Load each rung, measure the locators, drop the graph. Uses the LIGHT parse:
+ * entry counts come from backing-store edges, so the dominator/retained-size
+ * pass this tool would otherwise pay for on every rung buys nothing (measured
+ * on a 380 MB capture: 18s → 8s per rung).
+ */
+export declare function measureLadder(paths: string[], locators: Locator[], maxFileSizeMB?: number): Promise<{
+    labels: string[];
+    perRung: Map<string, LocatorMeasurement>[];
+}>;
+export declare function registerCollectionTrend(server: McpServer): void;
+//# sourceMappingURL=collection-trend.d.ts.map

package/dist/tools/collection-trend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-trend.d.ts","sourceRoot":"","sources":["../../src/tools/collection-trend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,cAAc,CAAC;AAC3D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAkBvE;;;;;;;;GAQG;AACH,MAAM,WAAW,OAAO;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAWlD;AAmBD,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,MAAM,EAAE,GACb,SAAS,GAAG,IAAI,CAOlB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAyC3D;AAED,MAAM,WAAW,kBAAkB;IAEjC,MAAM,EAAE,MAAM,CAAC;IAEf,QAAQ,EAAE,MAAM,CAAC;IAEjB,OAAO,EAAE,MAAM,CAAC;IAGhB,UAAU,EAAE,MAAM,CAAC;IAEnB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,OAAO,EAAE,GAClB,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAsCjC;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAAE,CAAA;CAAC,CAAC,CA+BzE;AAeD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAiK/D"}