@memlab/mcp-server 2.52.0 → 2.86.0

package/README.md

@@ -96,7 +96,11 @@ To auto-approve the read-only tools while keeping the two code-execution tools o
 
 ## How It Works
 
-The server holds a loaded `IHeapSnapshot` in memory across tool calls (loading is expensive for large heaps). Only one snapshot can be loaded at a time. All tools are read-only — they analyze the heap but never modify it.
+The server holds loaded `IHeapSnapshot` graphs in memory across tool calls (loading is
+expensive for large heaps). Several snapshots can be resident at once (`keep_previous: true`);
+tools read the active one, which `memlab_snapshots` switches. When a load's projected working
+set exceeds the free old-space budget, the least-recently-used resident snapshot is evicted
+before the load is refused. All tools are read-only — they analyze the heap but never modify it.
 
 ## Getting a Heap Snapshot
 
@@ -120,11 +124,14 @@ console.log(`Heap snapshot written to ${snapshot}`);
 ### `memlab_load_snapshot`
 
 Load and parse a `.heapsnapshot` file. Builds indexes, computes the dominator tree, and calculates retained sizes. `file_path` may be a local absolute path, a `manifold://bucket/key` URL, or a bare snapshot filename (resolved against the `nest_server_nodejs_heap_snapshots` bucket and fetched via `manifold get`). Pass `keep_previous: true` to keep earlier snapshots resident for diffing/comparison (each gets a handle; manage with `memlab_snapshots`). `quiet` / `suppress_suggestions` set session-wide output controls to trim repeated boilerplate.
+Pass `light: true` for a count-only load that skips the dominator / retained-size /
+shortest-path pass; tools needing retained sizes, dominators or retainer paths then return an
+error naming the light-safe tools instead of reporting zeros.
 
 ```
 Input:  { file_path: "snap.heapsnapshot" | "/abs/path" | "manifold://bucket/key",
           alias?: "before", keep_previous?: false, quiet?: false,
-          suppress_suggestions?: false, max_file_size_mb?: 900 }
+          suppress_suggestions?: false, light?: false, max_file_size_mb?: 900 }
 Output: { status, file_path, node_count, edge_count, total_size, handle }
 ```
 
@@ -148,6 +155,19 @@ Input:  { action?: "list"|"switch"|"unload", handle?: "before",
 Output: resident snapshots (active one marked), or switch/unload result
 ```
 
+### `memlab_batch`
+
+Run several tools against ONE snapshot load and return all their outputs together, instead of
+re-paying the multi-minute parse on every call. Steps run in order against the resident snapshot
+and see each other's side effects. An unknown tool name is rejected before any step runs, and by
+default a failing step is recorded and the batch continues.
+
+```
+Input:  { load?: { ...memlab_load_snapshot args }, steps: [{ tool, args? }],
+          stop_on_error?: false }
+Output: a per-step output block for each step, headed by a run/failed step count
+```
+
 ### `memlab_property_distribution`
 
 For a class/shape and a property, report value cardinality plus the top-K most frequent values. The key tool for diagnosing cardinality explosions (OTel metric attributes, cache keys, per-record fields).

package/dist/anonymized-snapshot.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 { IHeapSnapshot } from '@memlab/core';
+/**
+ * Has this capture had its string content replaced — and if so, in a way that
+ * corrupts the duplication numbers, or not?
+ *
+ * Anonymisers replace string CONTENT while preserving LENGTH. Whether that
+ * matters to an analysis depends entirely on which kind you are looking at, so
+ * this reports three states rather than a boolean:
+ *
+ * - `uniform` — every character replaced by ONE filler character. Every
+ *   distinct string of a given length collapses into the same value, so every
+ *   string-duplication analysis measures the anonymiser instead of the app.
+ *   Measured on one such capture: `memlab_quick_diagnosis` reported **"Total
+ *   interning savings: 47.4 MB"** and `memlab_duplicated_strings` reported a
+ *   single 5.2 KB string duplicated 939 times for 42.1 MB. Both were pure
+ *   artifact. Nothing flagged it; it was caught only because the sample values
+ *   rendered visibly as runs of `?`.
+ * - `stable` — replaced by a value-derived token, so distinctness survives
+ *   along with length. Duplication and interning figures are as true as on the
+ *   original capture, and warning about them would make readers discard
+ *   correct findings. Only the content is unreadable.
+ * - `none` — an ordinary capture.
+ *
+ * Both tests are deliberately cheap and deliberately conservative: sample
+ * strings, and only classify when a large majority match. A normal heap has
+ * plenty of short repeated-character strings ("  ", "----") and plenty of short
+ * lowercase words, so the length floor matters more than the ratio for either.
+ */
+export type AnonymizationKind = 
+/** ordinary capture */
+'none'
+/**
+ * every character replaced by one filler character. Length survives, so
+ * distinct values of equal length collapse into one and duplication figures
+ * become fiction.
+ */
+ | 'uniform'
+/**
+ * replaced by a value-derived token. Length AND distinctness survive, so
+ * duplication figures stay true; only the content is gone.
+ */
+ | 'stable';
+export interface AnonymizationCheck {
+    kind: AnonymizationKind;
+    /**
+     * true only for `uniform`, which is the kind that corrupts duplication
+     * numbers. Existing call sites read this to decide whether to warn, and a
+     * `stable` capture must NOT trip them — its numbers are trustworthy.
+     */
+    anonymized: boolean;
+    sampled: number;
+    singleCharRuns: number;
+    tokenRuns: number;
+    exampleChar?: string;
+}
+export declare function detectAnonymizedStrings(snapshot: IHeapSnapshot): AnonymizationCheck;
+/** The banner every string-content tool prints when the capture is anonymised. */
+export declare function anonymizedStringsBanner(check: AnonymizationCheck): string;
+/**
+ * Prepend the anonymisation banner to a tool's output when it applies.
+ *
+ * Wraps the result rather than being left to each caller to remember, because
+ * "remember to check" is exactly the failure this exists to prevent.
+ */
+export declare function withAnonymizedBanner(snapshot: IHeapSnapshot, text: string): string;
+//# sourceMappingURL=anonymized-snapshot.d.ts.map

package/dist/anonymized-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anonymized-snapshot.d.ts","sourceRoot":"","sources":["../src/anonymized-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,iBAAiB;AAC3B,uBAAuB;AACrB,MAAM;AACR;;;;GAIG;GACD,SAAS;AACX;;;GAGG;GACD,QAAQ,CAAC;AAEb,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,iBAAiB,CAAC;IACxB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAMD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,aAAa,GACtB,kBAAkB,CAqDpB;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAwBzE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,MAAM,GACX,MAAM,CAIR"}

package/dist/anonymized-snapshot.js

@@ -0,0 +1,101 @@
+/**
+ * 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
+ */
+const MIN_LEN = 8;
+const SAMPLE_TARGET = 400;
+const RATIO = 0.8;
+export function detectAnonymizedStrings(snapshot) {
+    let sampled = 0;
+    let singleCharRuns = 0;
+    let tokenRuns = 0;
+    let exampleChar;
+    let visited = 0;
+    snapshot.nodes.forEach(node => {
+        if (sampled >= SAMPLE_TARGET)
+            return;
+        if (node.type !== 'string')
+            return;
+        // Stride rather than take the first N: the first strings in a heap are
+        // V8 internals and interned literals, which are never anonymised and would
+        // make every capture look clean.
+        visited++;
+        if (visited % 7 !== 0)
+            return;
+        const value = node.name;
+        if (typeof value !== 'string' || value.length < MIN_LEN)
+            return;
+        sampled++;
+        const first = value[0];
+        let uniform = true;
+        for (let i = 1; i < value.length; i++) {
+            if (value[i] !== first) {
+                uniform = false;
+                break;
+            }
+        }
+        if (uniform) {
+            singleCharRuns++;
+            exampleChar ??= first;
+            return;
+        }
+        // `stable` fill is a run of lowercase letters and nothing else. Real string
+        // values of this length essentially always carry a space, digit, capital or
+        // punctuation mark somewhere, so a heap where most of them are bare
+        // lowercase runs has been rewritten.
+        if (/^[a-z]+$/.test(value)) {
+            tokenRuns++;
+        }
+    });
+    const uniformRatio = sampled >= 20 ? singleCharRuns / sampled : 0;
+    const tokenRatio = sampled >= 20 ? tokenRuns / sampled : 0;
+    const kind = uniformRatio >= RATIO ? 'uniform' : tokenRatio >= RATIO ? 'stable' : 'none';
+    return {
+        kind,
+        anonymized: kind === 'uniform',
+        sampled,
+        singleCharRuns,
+        tokenRuns,
+        exampleChar,
+    };
+}
+/** The banner every string-content tool prints when the capture is anonymised. */
+export function anonymizedStringsBanner(check) {
+    if (check.kind === 'stable') {
+        // Deliberately NOT a warning about the numbers. `stable` anonymization
+        // preserves distinctness, so duplication and interning figures are exactly
+        // as true as on the original capture — saying otherwise here would make
+        // readers discard correct findings.
+        const pct = check.sampled
+            ? Math.round((check.tokenRuns / check.sampled) * 100)
+            : 0;
+        return (`> ℹ️ **This capture is ANONYMISED (value-stable) — ${pct}% of sampled string values are opaque tokens.** ` +
+            'String CONTENT has been replaced, but lengths and distinctness were preserved, so counts, sizes, duplication and interning figures below are accurate. ' +
+            'What you cannot do is read the strings: a sample value tells you nothing about the real data, so identify records by property shape rather than by value.');
+    }
+    const pct = check.sampled
+        ? Math.round((check.singleCharRuns / check.sampled) * 100)
+        : 0;
+    return (`> ⚠️ **This capture looks ANONYMISED — ${pct}% of sampled strings are a single character (\`${check.exampleChar ?? '?'}\`) repeated.** ` +
+        'An anonymiser replaces string content but preserves length, so every distinct string of the same length collapses to the same value. ' +
+        '**Every duplication and interning figure below is manufactured by that collapse and does not exist in the real app.** ' +
+        'Do not quote them, and do not open an interning task from them. Composition, populations, retainer paths and dominator-deduped sizes are unaffected and remain trustworthy.');
+}
+/**
+ * Prepend the anonymisation banner to a tool's output when it applies.
+ *
+ * Wraps the result rather than being left to each caller to remember, because
+ * "remember to check" is exactly the failure this exists to prevent.
+ */
+export function withAnonymizedBanner(snapshot, text) {
+    const check = detectAnonymizedStrings(snapshot);
+    if (check.kind === 'none')
+        return text;
+    return `${anonymizedStringsBanner(check)}\n\n${text}`;
+}
+//# sourceMappingURL=anonymized-snapshot.js.map

package/dist/anonymized-snapshot.js.map

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

package/dist/eval-hints.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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
+ */
+/**
+ * Recognise an eval that is re-implementing a tool that already exists, and say
+ * so alongside the result.
+ *
+ * The discoverability problem this addresses is measured, not hypothetical: in
+ * one long session `memlab_eval_across`, `memlab_population_diff`,
+ * `memlab_event_registry`, `memlab_collection_trend` and `memlab_verify_fix`
+ * all existed, all would have saved work, and none was called — while the same
+ * questions were answered with hand-written evals, several times each. The
+ * operator had even read the warning about exactly this and still did not open
+ * the catalogue, because under time pressure writing the eval is the shorter
+ * path and nothing in that path mentions the alternative.
+ *
+ * So the hint is attached to the RESULT of the call that made the mistake,
+ * which is the one moment the caller is guaranteed to read. Two rules keep it
+ * from becoming noise:
+ *
+ *  - **Never suppress or alter the result.** The eval ran; the hint is a
+ *    footnote. A hint that blocked or replaced output would be worse than the
+ *    duplication it is trying to prevent.
+ *  - **Match on structure, not vocabulary.** A pattern fires only when the code
+ *    shows the SHAPE of the built-in's job (a `{callback, context}` census, a
+ *    per-class count keyed by snapshot, a detached-node distribution), not
+ *    merely because it mentions a word.
+ */
+export interface EvalHint {
+    tool: string;
+    why: string;
+}
+export declare function hintsForEval(code: string): EvalHint[];
+export declare function formatEvalHints(hints: EvalHint[]): string | null;
+//# sourceMappingURL=eval-hints.d.ts.map

package/dist/eval-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-hints.d.ts","sourceRoot":"","sources":["../src/eval-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAkGD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CASrD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,MAAM,GAAG,IAAI,CAKhE"}

package/dist/eval-hints.js

@@ -0,0 +1,115 @@
+/**
+ * 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
+ */
+const RULES = [
+    {
+        tool: 'memlab_event_registry',
+        why: 'counts `{callback, context}` listener records by event and host directly',
+        // `callback` and `context` are two of the most common identifiers in
+        // JavaScript, so matching them alone fires on evals that have nothing to do
+        // with listeners. Require the SHAPE as well: both read as properties off
+        // the same record, and the eval is accumulating or iterating over them.
+        all: [
+            /[.[]['"]?callback\b|\bcallback\s*:/,
+            /[.[]['"]?context\b|\bcontext\s*:/,
+            /&&|\+\+|\+= ?1|\|\| ?0\) ?\+ ?1|\?\? ?0\) ?\+ ?1|\.push\(|\bfor\b/,
+        ],
+        // Already going through the census tool, or bucketing something else.
+        none: [/memlab_event_registry/],
+    },
+    {
+        tool: 'memlab_detached_dom',
+        why: 'reports the detached-node population and its per-class distribution, using the same pinned/GC-eligible split the other tools use',
+        all: [/is_detached|isRealDetached|Detached </],
+        none: [/memlab_detached_dom/],
+    },
+    {
+        tool: 'memlab_census_diff',
+        why: 'takes the detached and listener census on BOTH rungs and diffs them per class in one call — no manual map-building or unload/reload cycle',
+        all: [
+            /is_detached|isRealDetached|Detached </,
+            /\bbaseline\b|\bbefore\b|\bprev\b/,
+        ],
+        none: [/memlab_census_diff/],
+    },
+    {
+        tool: 'memlab_class_histogram',
+        why: 'produces the per-class count/size table without a hand-written walk',
+        // Deliberately not keyed to the identifier `node`: the callback parameter
+        // is as often `n`, and requiring the long spelling made the rule silently
+        // never fire on the shape it exists to catch.
+        all: [
+            /snapshot\.nodes\.forEach|for\s*\(\s*const\s+\w+\s+of\s+snapshot\.nodes/,
+            /\.name\b/,
+            /\+\+|\+= ?1|\|\| ?0\) ?\+ ?1|\?\? ?0\) ?\+ ?1/,
+        ],
+        none: [/memlab_class_histogram|helpers\.classCounts/],
+    },
+    {
+        tool: 'memlab_ladder_probe',
+        why: 'runs ONE numeric probe across an ordered ladder and returns the series, the per-cycle rate and r² — loading one rung at a time, so it works on captures too large to hold simultaneously',
+        all: [/helpers\.(save|load)\(|__rung|perRung|per_rung/],
+        none: [/memlab_ladder_probe/],
+    },
+    {
+        tool: 'memlab_duplicate_objects',
+        why: 'is a ready-made dedup report over object content signatures',
+        all: [/shapeSignature|objectContentSignature/, /\bMap\b|\bSet\b/],
+        none: [/memlab_duplicate_objects/],
+    },
+    {
+        // One canonical tool name per hint. The pair used to be crammed into this
+        // single field, which rendered as one backticked identifier containing a
+        // slash and spaces — not a name any caller or renderer can resolve. The
+        // sibling tool goes in `why`, as prose, where it belongs.
+        tool: 'memlab_map_entries',
+        why: 'enumerates collection entries without the backing-store walk (see `memlab_weakmap_entries` for WeakMaps)',
+        all: [/table|backing/i, /\bMap\b|\bWeakMap\b/],
+        none: [
+            /helpers\.mapEntries|helpers\.weakmapEntries/,
+            /memlab_map_entries|memlab_weakmap_entries/,
+        ],
+    },
+    {
+        tool: 'memlab_retainer_trace',
+        why: 'walks retainer paths with framework filtering and path collapsing already applied',
+        all: [
+            /\.referrers\b/,
+            /while\s*\(|for\s*\(/,
+            /pathEdge|dominatorNode|\.referrers\[0\]/,
+        ],
+        none: [/memlab_retainer_trace|helpers\.pathBetween/],
+    },
+];
+/**
+ * At most this many hints per call. Beyond two the footnote stops being a
+ * pointer and starts being a second result the caller has to read.
+ */
+const MAX_HINTS = 2;
+export function hintsForEval(code) {
+    const hints = [];
+    for (const rule of RULES) {
+        if (hints.length >= MAX_HINTS)
+            break;
+        if (rule.none?.some(re => re.test(code)))
+            continue;
+        if (!rule.all.every(re => re.test(code)))
+            continue;
+        hints.push({ tool: rule.tool, why: rule.why });
+    }
+    return hints;
+}
+export function formatEvalHints(hints) {
+    if (hints.length === 0)
+        return null;
+    return hints
+        .map(h => `note: \`${h.tool}\` does this directly — it ${h.why}.`)
+        .join('\n');
+}
+//# sourceMappingURL=eval-hints.js.map

package/dist/eval-hints.js.map

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

package/dist/heap-budget.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { IHeapSnapshot } from '@memlab/core';
+import type { ArtifactKind } from './artifact-classes.js';
+import type { DevOnlyTotals, DevRootCategory } from './tools/dev-artifacts.js';
+export interface HeapBudget {
+    total: number;
+    app: number;
+    appNodes: number;
+    bundle: number;
+    code: number;
+    devOnly: number;
+    artifact: number;
+    /** Known-artifact self bytes split by family (warmup / ax / cdp-* / …). */
+    artifactByKind: Map<ArtifactKind, number>;
+    /** Dev-only totals split by root family, or null when no dev roots exist. */
+    devOnlyTotals: DevOnlyTotals | null;
+}
+export declare function computeHeapBudget(snapshot: IHeapSnapshot): HeapBudget;
+export declare function devFamilyBytes(budget: HeapBudget): Array<{
+    family: DevRootCategory;
+    nodes: number;
+    selfBytes: number;
+}>;
+//# sourceMappingURL=heap-budget.d.ts.map

package/dist/heap-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-budget.d.ts","sourceRoot":"","sources":["../src/heap-budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAY,aAAa,EAAC,MAAM,cAAc,CAAC;AAE3D,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AAMxD,OAAO,KAAK,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,0BAA0B,CAAC;AAmB7E,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,cAAc,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,UAAU,CA2DrE;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,GACjB,KAAK,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAAC,CAapE"}

package/dist/heap-budget.js

@@ -0,0 +1,90 @@
+/**
+ * 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 { classifyArtifact } from './artifact-classes.js';
+import { collectDevRoots, computeReachableWithoutDevRoots, summarizeDevOnly, } from './tools/dev-artifacts.js';
+/**
+ * The one bucket split of a heap into "app" and the several distinct reasons a
+ * byte might not be the app.
+ *
+ * Extracted so `memlab_app_heap` and `memlab_artifact_budget` cannot drift: they
+ * are two views of the same partition, and two implementations of "what counts
+ * as the app" that disagree by a few percent is worse than either one alone,
+ * because the disagreement is invisible in each tool's own output.
+ */
+const CODE_TYPES = new Set(['code']);
+// Bundle source text and the V8 structures that hold it. These exist because
+// the app was *loaded*, not because it did anything.
+const BUNDLE_NAME_RE = /ExternalStringData|InstructionStream|BytecodeArray|SharedFunctionInfo|ScopeInfo|UncompiledData|FeedbackVector|FeedbackMetadata|FeedbackCell|ClosureFeedbackCellArray|\(constant pool\)|ConstantPool/;
+export function computeHeapBudget(snapshot) {
+    const devRoots = collectDevRoots(snapshot);
+    const reached = devRoots.byId.size > 0
+        ? computeReachableWithoutDevRoots(snapshot, devRoots)
+        : null;
+    let total = 0;
+    let code = 0;
+    let bundle = 0;
+    let devOnly = 0;
+    let artifact = 0;
+    let app = 0;
+    let appNodes = 0;
+    const artifactByKind = new Map();
+    const isDevOnly = (node) => reached != null && reached[node.nodeIndex] === 0;
+    snapshot.nodes.forEach((node) => {
+        if (node.id <= 3)
+            return;
+        const size = node.self_size;
+        total += size;
+        // Precedence matters: a node is counted once, in the most specific bucket
+        // that explains why it is NOT app memory.
+        if (isDevOnly(node)) {
+            devOnly += size;
+            return;
+        }
+        if (CODE_TYPES.has(node.type)) {
+            code += size;
+            return;
+        }
+        if (BUNDLE_NAME_RE.test(node.name)) {
+            bundle += size;
+            return;
+        }
+        const kind = classifyArtifact(node.name);
+        if (kind != null) {
+            artifact += size;
+            artifactByKind.set(kind, (artifactByKind.get(kind) ?? 0) + size);
+            return;
+        }
+        app += size;
+        appNodes++;
+    });
+    return {
+        total,
+        app,
+        appNodes,
+        bundle,
+        code,
+        devOnly,
+        artifact,
+        artifactByKind,
+        devOnlyTotals: reached != null ? summarizeDevOnly(snapshot, devRoots, reached) : null,
+    };
+}
+export function devFamilyBytes(budget) {
+    const out = [];
+    const byCategory = budget.devOnlyTotals?.byCategory;
+    if (byCategory == null)
+        return out;
+    for (const [family, v] of byCategory) {
+        out.push({ family, nodes: v.nodes, selfBytes: v.selfBytes });
+    }
+    out.sort((a, b) => b.selfBytes - a.selfBytes);
+    return out;
+}
+//# sourceMappingURL=heap-budget.js.map

package/dist/heap-budget.js.map

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