@hydranium/cli 1.0.0-next.10

package/heap-analysis/heap/core/aggregate.mjs

@@ -0,0 +1,152 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Heap-agnostic aggregation primitives.
+ *
+ * Three distinct size views, deliberately kept separate because they answer
+ * different questions and must never be conflated:
+ *
+ *  - SHALLOW (self_size): the one clean additive partition of the heap. Sums
+ *    to 100%. Use this for "share of heap".
+ *  - RETAINED, OVERLAPPING (node.retainedSize summed per bucket): the
+ *    DevTools "Summary" number. OVERLAPS across buckets (a parent's retained
+ *    includes its children, which are their own rows) -> never sum these rows.
+ *  - RETAINED, EXCLUSIVE (dominator attribution): each byte attributed once to
+ *    the nearest anchor that dominates it. Non-overlapping; partitions the heap
+ *    among the anchors + "(root/shared)". This is the honest "how much frees if
+ *    this concept goes away" number.
+ */
+import { bucketLabel } from './bucket-label.mjs';
+
+/**
+ * One pass: shallow + overlapping-retained + count per label.
+ * Also returns flat typed arrays (indexed by node.nodeIndex) needed for the
+ * dominator-attribution pass, so callers don't iterate the heap twice.
+ *
+ * @param {import('@memlab/core').IHeapSnapshot} heap
+ * @param {(node: import('@memlab/core').IHeapNode) => string} [labelFn]
+ *   maps a node to its bucket label (defaults to the heap-agnostic
+ *   constructor/type label; the Langium layer passes a concept classifier)
+ */
+export function aggregateByBucket(heap, labelFn = bucketLabel) {
+   const byBucket = new Map(); // label -> { count, shallow, retainedOverlapping }
+   const nodeCount = heap.nodes.length;
+   const selfSize = new Float64Array(nodeCount);
+   const domIndex = new Int32Array(nodeCount).fill(-1);
+   const labelOfIndex = new Array(nodeCount);
+
+   heap.nodes.forEach(node => {
+      const label = labelFn(node);
+      const entry = byBucket.get(label) ?? { count: 0, shallow: 0, retainedOverlapping: 0 };
+      entry.count++;
+      entry.shallow += node.self_size;
+      entry.retainedOverlapping += node.retainedSize;
+      byBucket.set(label, entry);
+
+      const idx = node.nodeIndex;
+      selfSize[idx] = node.self_size;
+      labelOfIndex[idx] = label;
+      domIndex[idx] = node.dominatorNode ? node.dominatorNode.nodeIndex : -1;
+   });
+
+   return { byBucket, selfSize, domIndex, labelOfIndex };
+}
+
+/**
+ * Non-overlapping retained attribution via the dominator tree.
+ *
+ * For every node, walk up its dominator chain to the first node whose bucket
+ * label is in `anchors`; attribute the node's self_size there. Nodes with no
+ * anchor ancestor land in "(root/shared)". The result partitions the entire
+ * heap among anchors + "(root/shared)" with no double counting.
+ *
+ * Memoized per node index, so total work is ~O(nodeCount).
+ *
+ * @param {{selfSize: Float64Array, domIndex: Int32Array, labelOfIndex: string[]}} arrays
+ * @param {Set<string>} anchors bucket labels treated as ownership boundaries
+ */
+export function attributeExclusiveRetained({ selfSize, domIndex, labelOfIndex }, anchors) {
+   const nodeCount = selfSize.length;
+   const ROOT_SHARED = -1;
+   const UNVISITED = -2;
+   const IN_PROGRESS = -3;
+   const ownerOf = new Int32Array(nodeCount).fill(UNVISITED);
+
+   // Resolve the owning anchor index for a node, memoizing the whole chain.
+   // Robust against dominator-chain cycles (the synthetic GC root dominates
+   // itself; any node still IN_PROGRESS when revisited is treated as root).
+   const resolveOwner = startIdx => {
+      const chain = [];
+      let idx = startIdx;
+      let owner = ROOT_SHARED;
+      while (idx >= 0) {
+         const memo = ownerOf[idx];
+         if (memo === IN_PROGRESS) {
+            break; // cycle -> root/shared
+         }
+         if (memo !== UNVISITED) {
+            owner = memo; // already resolved; chain shares its owner
+            break;
+         }
+         if (anchors.has(labelOfIndex[idx])) {
+            ownerOf[idx] = idx; // anchor owns itself and the chain below it
+            owner = idx;
+            break;
+         }
+         ownerOf[idx] = IN_PROGRESS;
+         chain.push(idx);
+         idx = domIndex[idx];
+      }
+      for (const chainIdx of chain) {
+         ownerOf[chainIdx] = owner;
+      }
+      return owner;
+   };
+
+   for (let i = 0; i < nodeCount; i++) {
+      if (ownerOf[i] === UNVISITED) {
+         resolveOwner(i);
+      }
+   }
+
+   // Sum self_size into the owner's bucket label.
+   const exclusiveByLabel = new Map();
+   for (let i = 0; i < nodeCount; i++) {
+      const owner = ownerOf[i];
+      const label = owner === ROOT_SHARED ? '(root/shared)' : labelOfIndex[owner];
+      exclusiveByLabel.set(label, (exclusiveByLabel.get(label) ?? 0) + selfSize[i]);
+   }
+   return exclusiveByLabel;
+}
+
+/**
+ * Shortest retainer path from a node up to a GC root, using memlab's pathEdge
+ * (the incoming edge on the shortest path to root). Returns a list of hops
+ * [{ via, from }] from the node outward to the root.
+ *
+ * @param {import('@memlab/core').IHeapNode} node
+ * @param {number} [maxDepth]
+ */
+export function shortestRetainerPath(node, maxDepth = 12) {
+   const hops = [];
+   let current = node;
+   let depth = 0;
+   while (current && current.pathEdge && depth < maxDepth) {
+      const edge = current.pathEdge;
+      const from = edge.fromNode;
+      hops.push({
+         via: edge.is_index ? `[${edge.name_or_index}]` : String(edge.name_or_index),
+         from: from.type === 'object' ? from.name || '(object)' : `(${from.type})`
+      });
+      current = from;
+      depth++;
+   }
+   return hops;
+}

package/heap-analysis/heap/core/bucket-label.mjs

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * The default node bucket label. Kept in its own module — separate from the
+ * memlab-backed loader (load.mjs) — so the aggregation modules that need it
+ * (aggregate/holders/cutpoints) do not transitively pull @memlab/heap-analysis
+ * into the memlab-free `--diff` / `--help` paths.
+ */
+
+/**
+ * Canonical bucket label for a node: a JS object is labelled by its
+ * constructor name; everything else by its V8 type in parentheses.
+ */
+export function bucketLabel(node) {
+   return node.type === 'object' ? node.name || '(anonymous object)' : `(${node.type})`;
+}

package/heap-analysis/heap/core/cutpoints.mjs

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Cut points (heap-agnostic): lightweight SOLE owners of large subtrees.
+ *
+ * A node with tiny shallow size but huge retained size dominates a big subtree
+ * it alone keeps alive -- severing the few references to it frees the whole
+ * subtree. These are the highest-leverage things to drop. Few referrers = easy
+ * to cut; many referrers = the retained subtree is shared and won't free.
+ */
+import { bucketLabel } from './bucket-label.mjs';
+
+/**
+ * @param {import('@memlab/core').IHeapSnapshot} heap
+ * @param {string[]} labelOfIndex per-nodeIndex concept label (for readable names)
+ * @param {{ minRetained?: number, maxShallow?: number, topN?: number }} [opts]
+ */
+export function findCutPoints(heap, labelOfIndex, { minRetained = 512 * 1024, maxShallow = 4096, topN = 20 } = {}) {
+   const candidates = [];
+   heap.nodes.forEach(node => {
+      // Skip the GC super-root(s): they "retain everything" but aren't a cut point.
+      if (node.type === 'synthetic') {
+         return;
+      }
+      if (node.retainedSize >= minRetained && node.self_size <= maxShallow) {
+         // The shortest-path-to-root edge names what holds this node — `Holder.edge`
+         // — so otherwise-identical cut points (e.g. several `Map`s) are told apart.
+         const pathEdge = node.pathEdge;
+         const from = pathEdge?.fromNode;
+         const via = pathEdge ? (pathEdge.is_index ? '[]' : pathEdge.name_or_index) : '';
+         const retainer = from ? `${labelOfIndex[from.nodeIndex] || bucketLabel(from)}.${via}` : '';
+         candidates.push({
+            node,
+            label: labelOfIndex[node.nodeIndex] || bucketLabel(node),
+            shallow: node.self_size,
+            retained: node.retainedSize,
+            referrers: node.numOfReferrers,
+            retainer
+         });
+      }
+   });
+   candidates.sort((a, b) => b.retained - a.retained);
+   return candidates.slice(0, topN);
+}

package/heap-analysis/heap/core/diff.mjs

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Deterministic diff of two analysis JSONs (heap-agnostic). Pure arithmetic on
+ * already-computed analyses -- no snapshot or source needed, so it is instant
+ * and CI-safe. Baselines are the small JSON artifacts written by `--json`.
+ */
+
+/** Union the keys of two count/size maps and emit per-key deltas, sorted by |delta|. */
+function deltaRows(baseMap = {}, curMap = {}, pick) {
+   const keys = new Set([...Object.keys(baseMap), ...Object.keys(curMap)]);
+   const rows = [];
+   for (const key of keys) {
+      const base = pick(baseMap[key]);
+      const cur = pick(curMap[key]);
+      if (base !== cur) {
+         rows.push({ key, base, cur, delta: cur - base });
+      }
+   }
+   rows.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+   return rows;
+}
+
+/**
+ * @param {object} base baseline analysis JSON (from --json)
+ * @param {object} cur current analysis JSON
+ * @param {number} thresholdPct fraction of baseline total-shallow growth that
+ *   counts as a regression (e.g. 0.05 = 5%)
+ */
+export function diffAnalyses(base, cur, thresholdPct) {
+   const concepts = deltaRows(base.concepts, cur.concepts, e => e?.exclusive ?? 0);
+   const conceptsShallow = deltaRows(base.concepts, cur.concepts, e => e?.shallow ?? 0);
+   const ast = deltaRows(base.astByType, cur.astByType, v => v ?? 0);
+
+   const baseTotal = base.totalShallowBytes ?? 0;
+   const curTotal = cur.totalShallowBytes ?? 0;
+   const totalDelta = curTotal - baseTotal;
+   const growthPct = baseTotal ? totalDelta / baseTotal : 0;
+   const regressed = growthPct > thresholdPct;
+
+   return {
+      concepts,
+      conceptsShallow,
+      ast,
+      total: { base: baseTotal, cur: curTotal, delta: totalDelta, growthPct },
+      thresholdPct,
+      regressed
+   };
+}

package/heap-analysis/heap/core/format.mjs

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/* Tiny formatting helpers shared by the report renderers. */
+
+export const mb = bytes => `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+
+/**
+ * Adaptive byte size: MB for ≥1 MB, KB for ≥1 KB, else bytes. Keeps sub-MB table
+ * rows rankable instead of collapsing dozens of them to `0.0 MB`.
+ */
+export const humanBytes = bytes => {
+   const abs = Math.abs(bytes);
+   if (abs >= 1024 * 1024) {
+      return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+   }
+   if (abs >= 1024) {
+      return `${(bytes / 1024).toFixed(1)} KB`;
+   }
+   return `${Math.round(bytes)} B`;
+};
+
+export const pct = (part, whole) => (whole ? ((part / whole) * 100).toFixed(1) : '0.0') + '%';
+
+/** Wall-clock `[HH:MM:SS]` stamp for progress lines on long-running work. */
+export const nowStamp = () => `[${new Date().toTimeString().slice(0, 8)}]`;
+
+/** Emit a timestamped progress line to stderr (keeps stdout clean for results). */
+export function progress(message) {
+   process.stderr.write(`${nowStamp()} ${message}\n`);
+}
+
+/** Render rows [label, count, sizeBytes, ...extra] as an aligned table. */
+export function sizeTable(rows, { totalShallow } = {}) {
+   const lines = [];
+   for (const [label, count, size] of rows) {
+      const share = totalShallow ? `  ${pct(size, totalShallow).padStart(6)}` : '';
+      lines.push(`${mb(size).padStart(10)}${share}  ${String(count).padStart(10)}  ${label}`);
+   }
+   return lines.join('\n');
+}

package/heap-analysis/heap/core/holders.mjs

@@ -0,0 +1,80 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * "What holds X" retainer evidence (heap-agnostic).
+ *
+ * For every node matching a target predicate, tally two complementary views:
+ *   - dominators: the concept of each node's single dominatorNode -> who
+ *     EXCLUSIVELY owns it ("if I cut one thing, what frees").
+ *   - referrers: every incoming edge as `edgeName@holderLabel` -> ALL holders,
+ *     including shared references. Multiplicity here is why cutting one holder
+ *     can free little (e.g. CST held by parent CST AND $cstNode AND a description).
+ *
+ * Labels are taken from the caller-supplied per-node label array, so core stays
+ * ignorant of what the labels mean; the caller groups them for display.
+ */
+import { bucketLabel } from './bucket-label.mjs';
+
+/**
+ * Profile holders for SEVERAL target groups in a SINGLE heap pass (loading the
+ * snapshot is the only expensive step, so multiple --holders share one pass).
+ *
+ * @param {import('@memlab/core').IHeapSnapshot} heap
+ * @param {string[]} labelOfIndex per-nodeIndex classification label
+ * @param {Int32Array} domIndex per-nodeIndex dominator nodeIndex (-1 = root)
+ * @param {Set<string>} targetGroups concept groups to profile
+ * @param {(label: string) => string} groupOf collapse a label to its group
+ * @returns {Map<string, {targetCount, targetRetained, dominators, referrers}>}
+ */
+export function holderProfiles(heap, labelOfIndex, domIndex, targetGroups, groupOf) {
+   const results = new Map();
+   for (const group of targetGroups) {
+      results.set(group, { targetCount: 0, targetRetained: 0, dominators: new Map(), referrers: new Map() });
+   }
+
+   heap.nodes.forEach(node => {
+      const idx = node.nodeIndex;
+      const group = groupOf(labelOfIndex[idx]);
+      const result = results.get(group);
+      if (!result) {
+         return;
+      }
+      result.targetCount++;
+      result.targetRetained += node.retainedSize;
+
+      const dIdx = domIndex[idx];
+      const dLabel = dIdx >= 0 ? labelOfIndex[dIdx] : '(GC root)';
+      result.dominators.set(dLabel, (result.dominators.get(dLabel) ?? 0) + 1);
+
+      for (const edge of node.referrers) {
+         // __proto__ is the V8 prototype chain, not meaningful ownership -- skip it.
+         if (edge.name_or_index === '__proto__') {
+            continue;
+         }
+         const from = edge.fromNode;
+         const fromLabel = (from && labelOfIndex[from.nodeIndex]) || (from ? bucketLabel(from) : '(root)');
+         const name = edge.is_index ? '[]' : edge.name_or_index;
+         const key = `${name}@${fromLabel}`;
+         result.referrers.set(key, (result.referrers.get(key) ?? 0) + 1);
+      }
+   });
+
+   return results;
+}
+
+/** Regroup a tally Map's keys via a key-mapping function, summing collisions. */
+export function regroupTally(tally, mapKey) {
+   const out = new Map();
+   for (const [key, count] of tally) {
+      const grouped = mapKey(key);
+      out.set(grouped, (out.get(grouped) ?? 0) + count);
+   }
+   return out;
+}

package/heap-analysis/heap/core/load.mjs

@@ -0,0 +1,46 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Heap-agnostic loader. Wraps memlab's getFullHeapFromFile, which parses the
+ * .heapsnapshot and computes dominators + retained sizes natively.
+ *
+ * Nothing in core/ knows about Langium or any adopter's model.
+ */
+import { getFullHeapFromFile } from '@memlab/heap-analysis';
+import { progress } from './format.mjs';
+
+const mb = bytes => bytes / (1024 * 1024);
+
+/**
+ * Load a snapshot and return the memlab heap plus light meta.
+ * @param {string} file path to a .heapsnapshot
+ * @param {(msg: string) => void} [log] timestamped progress sink (defaults to stderr)
+ */
+export async function loadHeap(file, log = progress) {
+   const t0 = Date.now();
+   log(`Loading ${file} ...`);
+   const heap = await getFullHeapFromFile(file);
+   const loadSeconds = (Date.now() - t0) / 1000;
+
+   let totalShallow = 0;
+   heap.nodes.forEach(node => {
+      totalShallow += node.self_size;
+   });
+
+   const meta = {
+      snapshot: file,
+      nodeCount: heap.nodes.length,
+      totalShallowBytes: totalShallow,
+      totalShallowMb: Number(mb(totalShallow).toFixed(1)),
+      loadSeconds: Number(loadSeconds.toFixed(1))
+   };
+   log(`Loaded ${meta.nodeCount} nodes, ${meta.totalShallowMb} MB shallow in ${meta.loadSeconds}s`);
+   return { heap, meta };
+}

package/heap-analysis/heap/core/report.mjs

@@ -0,0 +1,68 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Minimal Markdown report builder. Accumulates sections (headings, prose,
+ * tables, code blocks) and renders to a single Markdown string -- readable as
+ * plain text in a terminal, saveable as a .md file, and cheap for a tool to
+ * parse (Markdown headings and tables).
+ */
+
+/** Escape `|` so a heap-derived cell value (e.g. a `A | B` union string) cannot shift table columns (GFM). */
+function escapeCell(value) {
+   return String(value).replace(/\|/g, '\\|');
+}
+
+export class Report {
+   constructor() {
+      this.lines = [];
+   }
+
+   /** Top-level title. */
+   title(text) {
+      this.lines.push(`# ${text}`, '');
+      return this;
+   }
+
+   /** Section heading (blank line before keeps sections separated). */
+   section(text) {
+      this.lines.push('', `## ${text}`, '');
+      return this;
+   }
+
+   /** A paragraph / note line. */
+   note(text) {
+      this.lines.push(text, '');
+      return this;
+   }
+
+   /**
+    * A Markdown table. `headers` is a string[]; `rows` is string[][]. Cells are
+    * stringified as-is (callers pre-format sizes/percentages).
+    */
+   table(headers, rows) {
+      this.lines.push(`| ${headers.map(escapeCell).join(' | ')} |`);
+      this.lines.push(`| ${headers.map(() => '---').join(' | ')} |`);
+      for (const row of rows) {
+         this.lines.push(`| ${row.map(escapeCell).join(' | ')} |`);
+      }
+      this.lines.push('');
+      return this;
+   }
+
+   /** A fenced code block (for retainer paths and other monospace content). */
+   code(text) {
+      this.lines.push('```', text, '```', '');
+      return this;
+   }
+
+   toString() {
+      return this.lines.join('\n');
+   }
+}

package/heap-analysis/heap/core/strings.mjs

@@ -0,0 +1,80 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/*
+ * Duplicate-string analysis (heap-agnostic) — quantifies the interning lever.
+ *
+ * V8 does not intern most runtime strings, so the same value (a name, a $type
+ * tag, a qualified id) can exist as many separate string nodes. Grouping string
+ * nodes by value shows how much could be reclaimed by interning to one copy.
+ *
+ * Only plain `string` nodes are analysed: memlab exposes their value via
+ * node.name. `concatenated string` (cons) nodes report a placeholder name, not
+ * their materialized text, so they cannot be value-deduped here -- they are a
+ * SEPARATE lever (compute the qualified/combined ids on demand instead of
+ * building them), quantified by their bucket size in the concept table.
+ */
+
+/**
+ * @param {import('@memlab/core').IHeapSnapshot} heap
+ * @param {{ types?: string[], maxLen?: number }} [opts]
+ *   types: which V8 string node types to include; maxLen: skip values longer
+ *   than this as interning candidates (big unique blobs like source text).
+ */
+export function duplicateStrings(heap, { types = ['string'], maxLen = 512 } = {}) {
+   const want = new Set(types);
+   const byValue = new Map(); // value -> { count, size, type }
+   let totalBytes = 0;
+   let totalNodes = 0;
+   let skippedLong = 0;
+
+   heap.nodes.forEach(node => {
+      if (!want.has(node.type)) {
+         return;
+      }
+      const value = node.name;
+      if (typeof value !== 'string') {
+         return;
+      }
+      totalNodes++;
+      totalBytes += node.self_size;
+      if (value.length > maxLen) {
+         skippedLong++;
+         return;
+      }
+      const entry = byValue.get(value);
+      if (entry) {
+         entry.count++;
+      } else {
+         byValue.set(value, { count: 1, size: node.self_size, type: node.type });
+      }
+   });
+
+   return { byValue, totalBytes, totalNodes, skippedLong };
+}
+
+/**
+ * Reduce a byValue map to ranked duplicates with reclaimable bytes
+ * (= (count - 1) * per-instance self_size, i.e. keep one copy).
+ */
+export function rankReclaimable(byValue) {
+   const dups = [];
+   let reclaimableTotal = 0;
+   let duplicatedValues = 0;
+   for (const [value, { count, size, type }] of byValue) {
+      if (count > 1) {
+         const reclaimable = (count - 1) * size;
+         reclaimableTotal += reclaimable;
+         duplicatedValues++;
+         dups.push({ value, count, size, type, reclaimable });
+      }
+   }
+   dups.sort((a, b) => b.reclaimable - a.reclaimable);
+   return { dups, reclaimableTotal, duplicatedValues, distinctValues: byValue.size };
+}