@ogygia/devtools 0.0.0 → 0.11.0

package/dist/profiler/insights.d.ts

@@ -0,0 +1,96 @@
+import { Analysis } from "./analyze.js";
+import { AwaitEdge, AwaitNode } from "./timeline.js";
+import { GcMaker } from "./gc.js";
+import { SpanRecord } from "./span.js";
+export interface SyncIoRow {
+  key: string;
+  name: string;
+  /** the node module (`node:fs`) */
+  module: string;
+  self_ms: number;
+  total_ms: number;
+  calls: number | null;
+  /** the app frames that called it, nearest first, from its hottest stack */
+  callers: string[];
+}
+/** Synchronous file, process, compression and key-derivation calls seen on the CPU during the
+ *  window: each one blocks every other request on the instance for its whole length. */
+export declare function sync_io(a: Analysis): SyncIoRow[];
+export interface MemoCandidate {
+  key: string;
+  name: string;
+  url: string;
+  line: number;
+  /** calls in one render (coverage) */
+  calls: number;
+  total_ms: number;
+  per_call_ms: number;
+  /** bytes it allocated per call, when the allocation profile saw it */
+  alloc_per_call?: number;
+  /** the component most of its calls sat under */
+  parent?: string;
+}
+/** App functions called many times per render at a steady cost each: what a cache keyed on the
+ *  argument would remove. Heuristic, from counts and cost alone: the report says so. */
+export declare function memo_candidates(a: Analysis, makers?: GcMaker[], limit?: number, runs?: number): MemoCandidate[];
+export type WhatIf = "parallel" | "cache" | "remove";
+export interface Simulation {
+  /** the render's wall as recorded and under the changes, ms */
+  before_ms: number;
+  after_ms: number;
+  delta_ms: number;
+  /** the longest chain of waits after the changes, in order */
+  chain: string[];
+  /** every node's new start and end */
+  nodes: {
+    label: string;
+    t0: number;
+    t1: number;
+    moved: boolean;
+  }[];
+}
+/** The render under a set of changes to its calls. The model: a call with a predecessor (an
+ *  edge: it started once the predecessor finished) starts when the predecessor ends plus the gap
+ *  that sat between them; a call without one keeps its recorded start; the CPU after the last
+ *  call keeps its length. `parallel` starts a call with its predecessor instead of after it,
+ *  `cache` makes it instant, `remove` takes it out. A model of the waits, not of the CPU. */
+export declare function simulate_awaits(nodes: AwaitNode[], edges: AwaitEdge[], window_ms: number, changes: Record<string, WhatIf>): Simulation;
+export interface SpanValueRow {
+  span: string;
+  attr: string;
+  n: number;
+  min: number;
+  p50: number;
+  max: number;
+  sum: number;
+  /** how the span's time moved with the value: ms per unit of the attribute (the slope of a
+   *  straight-line fit), when the value varied across at least 3 spans */
+  ms_per_unit?: number;
+  /** how well that line fits, -1..1 (near 1: the value drives the time) */
+  r?: number;
+}
+/** The NUMBERS the app attached to its spans (`span('db.query', fn, (rows) => ({ rows:
+ *  rows.length }))`): per span name and attribute, the range across the recording, and how
+ *  the span's time moved with the value — the cost per row, per tag, per byte. What a
+ *  function's name alone cannot say: the same function is cheap on 3 items and slow on 3000. */
+export declare function span_values(spans: readonly SpanRecord[] | undefined): SpanValueRow[];
+export interface RetainedSite {
+  name: string;
+  url: string;
+  line: number;
+  caller?: string;
+  component: string | null;
+  bytes: number;
+  share: number;
+  /** the app line it is charged to (the site when it is app code, else the nearest app caller) */
+  at?: {
+    path: string;
+    line: number;
+  };
+}
+export interface Retained {
+  /** bytes still alive after one more render and a full collection */
+  total_bytes: number;
+  render_ms: number;
+  sites: RetainedSite[];
+}

package/dist/profiler/insights.js

@@ -0,0 +1,239 @@
+// src/profiler/insights.ts
+const SYNC_IO = /* @__PURE__ */ new Set([
+	"readFileSync",
+	"writeFileSync",
+	"appendFileSync",
+	"readdirSync",
+	"statSync",
+	"lstatSync",
+	"fstatSync",
+	"existsSync",
+	"accessSync",
+	"mkdirSync",
+	"rmSync",
+	"rmdirSync",
+	"unlinkSync",
+	"copyFileSync",
+	"realpathSync",
+	"openSync",
+	"readSync",
+	"writeSync",
+	"closeSync",
+	"renameSync",
+	"execSync",
+	"execFileSync",
+	"spawnSync",
+	"gzipSync",
+	"gunzipSync",
+	"deflateSync",
+	"inflateSync",
+	"deflateRawSync",
+	"inflateRawSync",
+	"brotliCompressSync",
+	"brotliDecompressSync",
+	"pbkdf2Sync",
+	"scryptSync",
+	"hkdfSync",
+	"generateKeyPairSync"
+]);
+/** Synchronous file, process, compression and key-derivation calls seen on the CPU during the
+*  window: each one blocks every other request on the instance for its whole length. */
+function sync_io(a) {
+	const out = [];
+	for (const f of a.functions) {
+		if (!SYNC_IO.has(f.name)) continue;
+		if (f.category !== "node" && !f.url.startsWith("node:")) continue;
+		const callers = ((f.stacks ?? []).slice().sort((x, y) => y.ms - x.ms)[0]?.frames ?? []).filter((fr) => fr.c === "app" || fr.c === "component").slice(0, 3).map((fr) => fr.f ? `${fr.n} (${fr.f})` : fr.n);
+		out.push({
+			key: f.key,
+			name: f.name,
+			module: f.url.startsWith("node:") ? f.url.split("/")[0] : f.url || "node (native)",
+			self_ms: f.self_ms,
+			total_ms: f.total_ms,
+			calls: f.calls ?? null,
+			callers
+		});
+	}
+	return out.sort((x, y) => y.total_ms - x.total_ms);
+}
+const GLUE_RE = /^(?:\(anonymous\)|\$\.|get |set |render|children|slot|each_|if_|await_)/;
+/** request handlers and loads run once per request by design: not candidates */
+const HANDLER_NAMES = /* @__PURE__ */ new Set([
+	"load",
+	"handle",
+	"GET",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"fetch",
+	"resolve"
+]);
+const is_handler_file = (url) => url.includes("hooks.server") || url.includes("+server.");
+/** App functions called many times per render at a steady cost each: what a cache keyed on the
+*  argument would remove. Heuristic, from counts and cost alone: the report says so. */
+function memo_candidates(a, makers = [], limit = 8, runs = 1) {
+	const budget = Math.max(a.busy_ms / runs, 1);
+	const base = (u) => u.split("/").pop() ?? u;
+	const alloc_of = (f) => {
+		const b = base(f.url);
+		let sum = 0;
+		for (const m of makers) if (m.name === f.name && base(m.url) === b) sum += m.allocated;
+		else if (m.caller && m.caller.startsWith(f.name + " (") && m.caller.includes(b + ":")) sum += m.allocated;
+		return sum || void 0;
+	};
+	const out = [];
+	for (const f of a.functions) {
+		if (f.category !== "app") continue;
+		const calls = f.calls ?? 0;
+		if (calls < 10 || GLUE_RE.test(f.name) || HANDLER_NAMES.has(f.name) || is_handler_file(f.url)) continue;
+		const total = f.total_ms / runs;
+		if (total < Math.max(2, budget * .005)) continue;
+		const per_call = total / calls;
+		if (per_call < .02) continue;
+		const alloc = alloc_of(f);
+		out.push({
+			key: f.key,
+			name: f.name,
+			url: f.url,
+			line: f.line,
+			calls: Math.round(calls),
+			total_ms: Math.round(total * 100) / 100,
+			per_call_ms: Math.round(per_call * 1e3) / 1e3,
+			...alloc ? { alloc_per_call: Math.round(alloc / runs / calls) } : {},
+			...f.parent ? { parent: f.parent } : {}
+		});
+	}
+	return out.sort((x, y) => y.total_ms - x.total_ms).slice(0, limit);
+}
+/** The render under a set of changes to its calls. The model: a call with a predecessor (an
+*  edge: it started once the predecessor finished) starts when the predecessor ends plus the gap
+*  that sat between them; a call without one keeps its recorded start; the CPU after the last
+*  call keeps its length. `parallel` starts a call with its predecessor instead of after it,
+*  `cache` makes it instant, `remove` takes it out. A model of the waits, not of the CPU. */
+function simulate_awaits(nodes, edges, window_ms, changes) {
+	const idx = nodes.map((n, i) => ({
+		...n,
+		i
+	})).sort((a, b) => a.t0 - b.t0);
+	const by_label = /* @__PURE__ */ new Map();
+	for (const n of idx) (by_label.get(n.label) ?? by_label.set(n.label, []).get(n.label)).push(n);
+	const pred = /* @__PURE__ */ new Map();
+	for (const e of edges) for (const b of by_label.get(e.to) ?? []) {
+		if (pred.has(b.i)) continue;
+		let best;
+		for (const a of by_label.get(e.from) ?? []) if (a.t1 <= b.t0 + .05 && (!best || a.t1 > best.t1)) best = a;
+		if (best) pred.set(b.i, {
+			p: best,
+			gap: e.gap_ms
+		});
+	}
+	const last_end = Math.max(0, ...nodes.map((n) => n.t1));
+	const tail = Math.max(0, window_ms - last_end);
+	const start = /* @__PURE__ */ new Map();
+	const end = /* @__PURE__ */ new Map();
+	const chain_of = /* @__PURE__ */ new Map();
+	for (const n of idx) {
+		const change = changes[n.label];
+		const dur = change === "cache" || change === "remove" ? 0 : n.t1 - n.t0;
+		const pr = pred.get(n.i);
+		let t0;
+		let chain;
+		if (pr && change !== "remove") {
+			const p_change = changes[pr.p.label];
+			const p_start = start.get(pr.p.i) ?? pr.p.t0;
+			const p_end = end.get(pr.p.i) ?? pr.p.t1;
+			t0 = p_change === "remove" ? Math.min(n.t0, p_start) : change === "parallel" ? p_start : p_end + pr.gap;
+			chain = [...chain_of.get(pr.p.i) ?? [pr.p.label], n.label];
+		} else {
+			t0 = n.t0;
+			chain = [n.label];
+		}
+		start.set(n.i, t0);
+		end.set(n.i, t0 + dur);
+		chain_of.set(n.i, chain);
+	}
+	let after_last = 0;
+	let longest = [];
+	for (const n of idx) {
+		if (changes[n.label] === "remove") continue;
+		const e = end.get(n.i);
+		if (e > after_last) {
+			after_last = e;
+			longest = chain_of.get(n.i) ?? [];
+		}
+	}
+	const after_ms = Math.round((after_last + tail) * 100) / 100;
+	return {
+		before_ms: window_ms,
+		after_ms,
+		delta_ms: Math.round((after_ms - window_ms) * 100) / 100,
+		chain: longest,
+		nodes: idx.map((n) => ({
+			label: n.label,
+			t0: Math.round((start.get(n.i) ?? n.t0) * 100) / 100,
+			t1: Math.round((end.get(n.i) ?? n.t1) * 100) / 100,
+			moved: Math.abs((start.get(n.i) ?? n.t0) - n.t0) > .05 || changes[n.label] !== void 0
+		}))
+	};
+}
+/** The NUMBERS the app attached to its spans (`span('db.query', fn, (rows) => ({ rows:
+*  rows.length }))`): per span name and attribute, the range across the recording, and how
+*  the span's time moved with the value — the cost per row, per tag, per byte. What a
+*  function's name alone cannot say: the same function is cheap on 3 items and slow on 3000. */
+function span_values(spans) {
+	if (!spans?.length) return [];
+	const by = /* @__PURE__ */ new Map();
+	for (const s of spans) {
+		if (!s.attrs || s.ms < 0) continue;
+		for (const k in s.attrs) {
+			const v = s.attrs[k];
+			if (typeof v !== "number" || !Number.isFinite(v)) continue;
+			const key = s.name + "\0" + k;
+			let e = by.get(key);
+			if (!e) by.set(key, e = {
+				values: [],
+				ms: []
+			});
+			e.values.push(v);
+			e.ms.push(s.ms);
+		}
+	}
+	const out = [];
+	for (const [key, e] of by) {
+		const at = key.indexOf("\0");
+		const sorted = [...e.values].sort((a, b) => a - b);
+		const n = sorted.length;
+		const sum = sorted.reduce((a, b) => a + b, 0);
+		const row = {
+			span: key.slice(0, at),
+			attr: key.slice(at + 1),
+			n,
+			min: sorted[0],
+			p50: sorted[n >> 1],
+			max: sorted[n - 1],
+			sum: Math.round(sum * 1e3) / 1e3
+		};
+		if (n >= 3 && sorted[n - 1] - sorted[0] >= Math.abs(sorted[n - 1]) * .05) {
+			const mx = sum / n;
+			const my = e.ms.reduce((a, b) => a + b, 0) / n;
+			let sxy = 0;
+			let sxx = 0;
+			let syy = 0;
+			for (let i = 0; i < n; i++) {
+				const dx = e.values[i] - mx;
+				const dy = e.ms[i] - my;
+				sxy += dx * dy;
+				sxx += dx * dx;
+				syy += dy * dy;
+			}
+			if (sxx > 0) {
+				row.ms_per_unit = Math.round(sxy / sxx * 1e4) / 1e4;
+				row.r = syy > 0 ? Math.round(sxy / Math.sqrt(sxx * syy) * 100) / 100 : 0;
+			}
+		}
+		out.push(row);
+	}
+	return out.sort((a, b) => b.n - a.n || a.span.localeCompare(b.span));
+}
+export { memo_candidates, simulate_awaits, span_values, sync_io };

package/dist/profiler/ledger.d.ts

@@ -0,0 +1,121 @@
+import { FrameStat } from "./analyze.js";
+import { GcMaker } from "./gc.js";
+import { RetainedSite } from "./insights.js";
+export interface LedgerLine {
+  /** the resolved source path (the join key, with `line`) */
+  path: string;
+  /** a short display path */
+  file: string;
+  line: number;
+  /** a line of a BUILT chunk (no sourcemap): the source module whose code it is, from the build's
+   *  module map (`src/lib/format.ts`) — the line number stays the chunk's */
+  module?: string;
+  /** the code on that line, when the source was available */
+  code?: string;
+  /** CPU self time that landed on this line, ms */
+  cpu_ms: number;
+  /** bytes allocated by this line (or by builtins it called) */
+  alloc_bytes: number;
+  /** GC pause time those allocations caused, ms */
+  gc_ms: number;
+  /** bytes still alive after one more render and a full collection */
+  retained_bytes: number;
+  /** the functions and builtins whose cost landed here (`formatPrice`, `replace`), heaviest first */
+  who: string[];
+  /** the key of the function whose CPU landed here most (its row in the functions table) */
+  fn?: string;
+  /** the memory numbers are the whole function's, folded onto its hottest line: an allocation
+   *  profile sees the function an allocation happened in, never the line */
+  mem_in_fn?: boolean;
+  /** some of the memory numbers were made INSIDE this package, which the line calls, with no app
+   *  frame above them (the library's work after an await): charged here, the way its CPU is */
+  mem_via?: string;
+  /** the growth check's verdict on what this line kept: still growing render after render
+   *  (`true`), or flat after the first (`false`, a bounded cache); absent when it did not run */
+  grows?: boolean;
+  /** CPU spent inside libraries (dependencies, Node) that THIS line called, ms: a CPU profile
+   *  never records a call site, so it is found by reading the calling function's source for the
+   *  library function's name (or its import alias) — split evenly when it is called on several */
+  lib_ms: number;
+  /** those library calls, heaviest first */
+  libs?: LibCall[];
+  /** the line's combined share of every cost in the ledger (0..3): how it ranks */
+  score: number;
+  /** its CPU was moved here from line `from`: V8 had inlined `callee` and charged its time there
+   *  (split by the un-inlined render's times) */
+  merged?: {
+    from: number;
+    callee: string;
+  };
+}
+export interface LibCall {
+  /** the library function's own name (`renderToString`) */
+  name: string;
+  /** its package (`@acme/ui`), `Node` for Node's own, '' when unknown */
+  pkg: string;
+  ms: number;
+  /** the call appears on this many lines of the caller, and `ms` is this line's even share */
+  shared?: number;
+}
+export interface LedgerInput {
+  functions: readonly FrameStat[];
+  makers?: readonly GcMaker[];
+  retained?: readonly RetainedSite[];
+  /** the growth check: what each site still held after `renders` more renders */
+  grown?: {
+    renders: number;
+    sites: readonly RetainedSite[];
+    half?: {
+      renders: number;
+      sites: readonly RetainedSite[];
+    };
+  };
+  /** the code on a source line (untrimmed is fine), or undefined */
+  code?: (path: string, line: number) => string | undefined;
+  /** lines `from`..`to` of a source (1-based, inclusive): what finds library call sites */
+  source?: (path: string, from: number, to: number) => {
+    start: number;
+    lines: string[];
+  } | undefined;
+  /** the app functions of a render profiled with V8's inlining OFF (the call-count render): each
+   *  keeps its own frame there, so its time says whose share a merged caller line holds */
+  uninlined?: readonly (Pick<FrameStat, "name" | "path" | "category" | "total_ms" | "lines"> & Partial<Pick<FrameStat, "key" | "line" | "url" | "callees">>)[];
+  /** the renders `functions` add up (page mode's runs); `uninlined` is one render */
+  renders?: number;
+  limit?: number;
+}
+/** the package of a `node_modules`-relative path: `@acme/ui/hydrate/x.mjs:1` → `@acme/ui` */
+export declare function pkg_of(file: string): string;
+/** the framework the app runs on: SvelteKit, Svelte, ogygia itself, Vite */
+export declare const is_framework_pkg: (p: string) => boolean;
+/** After `renders` more renders a leaking line holds about `renders` × what one render left; one
+ *  filling a bounded cache holds its capacity's worth. At 80 % of `renders`× or more it grew with
+ *  EVERY render measured. The limit, said plainly: a cache holding at least `renders` entries is
+ *  indistinguishable from a leak in that many renders. */
+export declare const grows_of: (grown: number, one: number, renders: number) => boolean | undefined;
+/** The steadier verdict: the same sampler read after `h` renders (`half`) and after `n` (`full`).
+ *  A leaking line holds `n/h` times as much at the end as halfway; one feeding a bounded cache
+ *  that filled holds about the same. The sampled objects are the same objects in both reads, so
+ *  one sample's noise cancels; the middle band is still no verdict. */
+export declare const grows_between: (half: number, full: number, h: number, n: number) => boolean | undefined;
+/** "grows" from the halfway read, CHECKED against the one-render amount: a leak holds about one
+ *  render's worth per render (all `renders` of them), a cache with a size limit holds its capacity.
+ *  The two sampled reads can land far enough apart by chance to read as growth (a 4-entry cache,
+ *  sampled low halfway and high at the end); a line holding well under the renders' worth is not
+ *  leaking — no verdict then. Stays "grows" when the one-render amount is unknown.
+ *  One render's worth is the LARGER of two estimates: the separate one-render pass, and the
+ *  halfway read over its renders (the same sampler as the end read, so their noise is shared).
+ *  A low draw on one of them no longer makes a filled cache look like a leak. */
+export declare const confirmed: (between: boolean | undefined, grown: number, one: number, renders: number, half?: {
+  bytes: number;
+  renders: number;
+}) => boolean | undefined;
+/** A readable path: from `src/` when the path has one, the package-relative path inside
+ *  `node_modules`, else the last three segments. */
+export declare function short_source(path: string): string;
+/** a source path the reader could open and edit: not a dependency, not Node's own, not the
+ *  framework's generated build output (a compiled route chunk nobody edits), and not ogygia's own
+ *  source reached through a workspace link (`packages/core/src/…`: no node_modules segment, but
+ *  the library all the same, as analyze's categorize already says) */
+export declare const is_app_path: (path: string) => boolean;
+export declare function build_ledger(input: LedgerInput): LedgerLine[];