@ogygia/devtools 0.0.0 → 0.11.1

package/dist/profiler/analyze.d.ts

@@ -0,0 +1,437 @@
+import { Timeline, TimelineInput } from "./timeline.js";
+import { another_routes_file, route_dirs, route_file_of } from "./route-files.js";
+export interface CallFrame {
+  functionName: string;
+  scriptId?: string;
+  url: string;
+  lineNumber: number;
+  columnNumber: number;
+}
+export declare function learn_script_urls(profile: {
+  nodes?: readonly ProfileNode[];
+} | null | undefined): void;
+/** a frame with its url filled from its script id when the profile left it empty */
+export declare function with_script_url(f: CallFrame): CallFrame;
+export interface ProfileNode {
+  id: number;
+  callFrame: CallFrame;
+  hitCount?: number;
+  children?: number[];
+  /** V8's per-LINE sample counts inside this function (1-based lines of the script) */
+  positionTicks?: {
+    line: number;
+    ticks: number;
+  }[];
+  /** why V8 threw this function out of optimized code, when it did (`wrong map`, `not a Smi`…) */
+  deoptReason?: string;
+}
+/** a function V8 deoptimized during the window, with the reasons it gave */
+export interface DeoptRow {
+  key: string;
+  name: string;
+  url: string;
+  line: number;
+  category: FrameCategory;
+  reasons: Record<string, number>;
+  count: number;
+  self_ms: number;
+}
+export interface CpuProfile {
+  nodes: ProfileNode[];
+  /** microseconds */
+  startTime: number;
+  /** microseconds */
+  endTime: number;
+  samples?: number[];
+  /** microseconds between consecutive samples */
+  timeDeltas?: number[];
+}
+export type FrameCategory = "component" | "app" | "dependency" | "svelte" | "node" | "gc" | "idle" | "v8" | "profiler" | "unknown";
+/** One call path into a function: the nearest callers first, and how much of the function's time
+ *  (inclusive — the subtree reached through this exact path) came this way. */
+export interface CallStack {
+  ms: number;
+  /** nearest caller first; `n` = display name, `f` = `file:line` ('' for native), `c` = category
+   *  (the UI dims framework/runtime frames so your own code stands out) */
+  frames: {
+    n: string;
+    f: string;
+    c: FrameCategory;
+  }[];
+}
+export interface FrameStat {
+  /** the aggregation identity (`C:<name>` for a component, `<name> <url>` otherwise) */
+  key: string;
+  name: string;
+  /** an anonymous app function's own first line, trimmed (`span('ds.splice', () => {`): what it
+   *  is, where a name cannot say */
+  label?: string;
+  /** short display path (last segments, or the node_modules-relative path) */
+  url: string;
+  /** the full path as V8 (or the sourcemap) reported it — absolute in dev, so it can be opened */
+  path: string;
+  line: number;
+  /** 1-based column; 0 when unknown */
+  col: number;
+  category: FrameCategory;
+  /** package name when category is 'dependency' */
+  pkg?: string;
+  /** ms spent exactly here */
+  self_ms: number;
+  /** ms spent here plus everything it called (recursion counted once) */
+  total_ms: number;
+  /** exact invocation count from V8 precise coverage, when available (this frame's own count) */
+  calls?: number;
+  /** the heaviest call paths into this function (filled for the hot functions and every component) */
+  stacks?: CallStack[];
+  /** components: ms spent BUILDING MARKUP — Svelte's server internals (escape, attr, push…) run
+   *  under this component with no nearer component — versus RUNNING LOGIC — its own script and
+   *  the app / dependency / node code it calls. Nested components are in neither. */
+  markup_ms?: number;
+  logic_ms?: number;
+  /** components: the component whose render contained most of this one's time — the parent of a
+   *  `{#each}` list's rows */
+  parent?: string;
+  /** THE HOT LINES: where inside this function the self time landed (V8's per-line ticks, mapped
+   *  through the sourcemap when one resolved), heaviest first */
+  lines?: {
+    line: number;
+    ms: number;
+  }[];
+  /** the source around the hot lines, captured at report time — from the sourcemap's embedded
+   *  copy (so it works on a deployed host with no source on disk) or the local file. Carried in
+   *  the report itself: the code shows in exports and share links with no request to make. */
+  src?: {
+    start: number;
+    lines: string[];
+  };
+  /** components, page mode: inclusive ms in EACH run — the spread says cache miss vs slow code */
+  runs_ms?: number[];
+  /** app functions and components: WHAT THIS ONE CALLED and how much of its total went into each
+   *  (inclusive ms; builtins, dependencies, other app code), heaviest first — where a function's
+   *  time goes when it is not its own lines */
+  callees?: Callee[];
+  /** library work this function started that ran AFTER an await (no app frame on its stacks),
+   *  charged to it by time; not part of `total_ms` */
+  async_ms?: number;
+}
+export interface Callee {
+  key: string;
+  name: string;
+  category: FrameCategory;
+  /** the package it belongs to, when the analyzer knows (a node_modules path, or the module map) */
+  pkg?: string;
+  /** short `file:line`, '' for a builtin */
+  file: string;
+  ms: number;
+  /** share of the caller's total */
+  share: number;
+  /** of `ms`, the part that ran after an await: library continuations with no app frame on their
+   *  stacks, charged to this caller as the app code that entered the library nearest in time */
+  async_ms?: number;
+}
+export interface GroupStat {
+  key: string;
+  category: FrameCategory;
+  self_ms: number;
+}
+export interface FlameNode {
+  /** display name */
+  n: string;
+  /** category (for coloring) */
+  c: FrameCategory;
+  /** total ms, rounded to 2dp */
+  t: number;
+  /** self ms */
+  s: number;
+  /** file:line, '' when none */
+  f: string;
+  ch?: FlameNode[];
+}
+/**
+ * ONE PATH, SEVERAL HOT FUNCTIONS: a caller in your code under which two or more of the hot
+ * functions burn their time. Fixing the caller once (cache its result, call it less, move it out
+ * of the render) addresses all of them, where the table would have you chase each on its own.
+ */
+export interface PathGroup {
+  /** the caller to fix: a component or an app function */
+  owner: {
+    key: string;
+    name: string;
+    url: string;
+    line: number;
+    category: FrameCategory;
+    total_ms: number;
+    calls?: number;
+  };
+  /** the hot functions under it, with the self time they burned on this path, heaviest first */
+  fns: {
+    key: string;
+    name: string;
+    url: string;
+    line: number;
+    category: FrameCategory;
+    pkg?: string;
+    ms: number;
+  }[];
+  /** their summed self time under the owner */
+  ms: number;
+  /** how much of the owner's inclusive time that is */
+  share: number;
+  /** the call tree from the owner down to the hot functions — only the branches that reach one */
+  tree: PathNode;
+}
+/** One node of a path tree: a frame between the owner and a hot function, or one of them. */
+export interface PathNode {
+  key: string;
+  name: string;
+  category: FrameCategory;
+  /** `file:line`, '' when none */
+  file: string;
+  /** ms of hot-function self time that flowed through this node on the path */
+  ms: number;
+  /** a hot function itself (a leaf of the path, or a hot caller of another hot function) */
+  hot: boolean;
+  /** how many times it was called across the window (from coverage), when known */
+  calls?: number | null;
+  children: PathNode[];
+}
+/** One resolved frame of the stack index: what a sample's stack is made of. */
+export interface StackFrameRef {
+  /** the frame's display name (sourcemapped, renamed like every other row) */
+  n: string;
+  /** `file:line`, when known */
+  f?: string;
+  c: FrameCategory;
+  /** the index of the parent frame in `frames`, -1 at a root */
+  p: number;
+}
+/**
+ * THE SAMPLES THEMSELVES, on the render's clock: every CPU sample inside the one window the
+ * report explains, as `(time, length, leaf frame)` with the frame table the leaves hang from.
+ * Every other table is an aggregate of this; this is the substrate they came from, so any range
+ * of the render can be asked "what ran here" and any instant "what was the stack" — without
+ * the raw profile (megabytes) and without re-resolving anything. Consecutive samples of one
+ * leaf are folded (one entry with the summed length); beyond `MAX_INDEX_SAMPLES` the folded
+ * entries are stride-sampled, the lengths kept so the sum still is the CPU time.
+ */
+export interface StackIndex {
+  frames: StackFrameRef[];
+  /** ms from the window's start, per sample */
+  t: number[];
+  /** ms each sample stands for */
+  d: number[];
+  /** the leaf frame per sample (an index into `frames`), -1 for an idle sample */
+  leaf: number[];
+  /** how many raw samples were folded into `t` */
+  raw: number;
+  window_ms: number;
+}
+export interface Analysis {
+  /** wall-clock length of the recording window in ms */
+  duration_ms: number;
+  /** ms the CPU was running the APP's JS/GC: everything except idle and the profiler's own frames */
+  busy_ms: number;
+  idle_ms: number;
+  gc_ms: number;
+  /** ms the CPU spent in the profiler's own code (its I/O tracker, its heap reads, its stack
+   *  captures): measured, reported, and kept OUT of every other number */
+  overhead_ms: number;
+  /** the profiler's own frames by self time (what the overhead was), a few */
+  overhead_functions: {
+    name: string;
+    url: string;
+    line: number;
+    self_ms: number;
+  }[];
+  /** page mode: the profiler's own CPU inside each run's window (what each run's wall time
+   *  carries that the app would not have paid); the rest of `overhead_ms` sits between runs
+   *  or before the first — the profiler's start-up scan of compiled code, its final reads */
+  overhead_by_run_ms?: number[];
+  /** the CPU segments over the WHOLE capture (every run), on the capture's clock — what was
+   *  running at any moment (the GC attribution names what ran when each pause fell) */
+  capture_cpu?: {
+    t0: number;
+    t1: number;
+    label: string;
+    category: FrameCategory;
+    file?: string;
+  }[];
+  /** page mode: each CPU owner's ms in every run (grouped as the drill-down groups them): how much
+   *  a row moves from one render to the next */
+  owner_runs_ms?: Record<string, number[]>;
+  /** functions V8 deoptimized during the window, by self time */
+  deopts: DeoptRow[];
+  sample_count: number;
+  /** every frame aggregated across the profile, sorted by self time desc */
+  functions: FrameStat[];
+  /** frames that look like Svelte component SSR functions, by total desc */
+  components: FrameStat[];
+  /** self time grouped by source file, desc */
+  files: GroupStat[];
+  /** self time grouped by npm package / category bucket, desc */
+  buckets: GroupStat[];
+  /** left-heavy call tree for the flamegraph, roots under a synthetic root */
+  flame: FlameNode;
+  /** true when at least one bundled frame was mapped back through a sourcemap */
+  sourcemapped: boolean;
+  /** CPU sampled under ANOTHER route's page or layout (another visitor's request, answered while
+   *  the profiled one rendered), set aside: ms over the whole window */
+  other_requests_ms?: number;
+  /** no sourcemaps, but the app's script modules were matched to their source by text (the
+   *  source on this machine): the lines, and so the fixes, are there */
+  text_mapped?: boolean;
+  /** ONE request's critical path + phases (page / request mode; absent for a plain window) */
+  timeline?: Timeline;
+  /** the samples inside that one window, with their stacks (the substrate every table came from) */
+  stacks?: StackIndex;
+  /** hot functions grouped by the one caller they share — the paths to fix, biggest first */
+  paths: PathGroup[];
+}
+/**
+ * The stack index of one window (see `StackIndex`). `frame_of` gives a node's resolved frame,
+ * `parent_of` its parent node; only nodes on a sampled stack inside the window enter the table.
+ */
+export declare function build_stack_index(profile: CpuProfile, frame_of: (id: number) => {
+  name: string;
+  url: string;
+  line: number;
+  category: FrameCategory;
+}, parent_of: (id: number) => number | undefined, perf_start: number, window: {
+  start: number;
+  end: number;
+}): StackIndex | undefined;
+/** A frame name with the bundler's `$N` collision suffix removed. */
+export declare function strip_bundler_suffix(name: string): string;
+export declare function component_name_from_file(url: string): string | undefined;
+export declare function clean_url(url: string): string;
+/**
+ * A sourcemap's `sources` are relative to the MAP FILE (`../../src/lib/Foo.svelte` from
+ * `.svelte-kit/output/server/chunks/x.js.map`). Joined onto the chunk's own directory they become
+ * the real path — absolute when V8 reported the chunk absolutely (a `vite preview`, adapter-node),
+ * which is what lets a row open in an editor. Pure string work (no `node:path`): this module runs
+ * anywhere. An absolute source, a URL, or a chunk with no directory passes through unchanged.
+ */
+export declare function join_source(chunk: string, source: string): string;
+export declare function categorize(frame: CallFrame): {
+  category: FrameCategory;
+  pkg?: string;
+};
+interface MappedLine {
+  /** generated column -> [column, source index, original line, name index (-1 = none), original column] */
+  cols: [number, number, number, number, number][];
+}
+/**
+ * A MAP'S MAPPINGS, PACKED: every segment as five numbers in one array — generated column, source
+ * index, original line, name index (-1 = none), original column — and where each generated line's
+ * segments start. A real app's server maps hold millions of segments; an array (and an object) per
+ * segment cost the profiler over 100 MB on one, the packed form about a fifth of that.
+ */
+export interface PackedMappings {
+  /** SEG numbers per segment */
+  segs: Int32Array;
+  /** generated line l's segments are `starts[l]` up to `starts[l + 1]` (segment indices) */
+  starts: Int32Array;
+}
+/** Decode one VLQ-encoded sourcemap `mappings` string, packed. */
+export declare function decode_packed(mappings: string): PackedMappings;
+/** Decode one VLQ-encoded sourcemap `mappings` string into per-line column maps (the readable
+ *  form of {@link decode_packed}) */
+export declare function decode_mappings(mappings: string): MappedLine[];
+export declare class SourceMapResolver {
+  #private;
+  /** whether any lookup succeeded */
+  hit: boolean;
+  /** whether any line of a chunk WITHOUT a map was matched to its source by text */
+  text_hit: boolean;
+  constructor(read: (path: string) => string | undefined, module_at?: ModuleAt, opts?: {
+    any_ext?: boolean;
+  });
+  /** every original source a loaded map carries a copy of */
+  embedded_sources(): IterableIterator<string>;
+  /** Lines `from`..`to` (1-based, inclusive) of an original source, untrimmed — the source view.
+   *  Undefined when the source is not available (no embedded copy, not on this machine). */
+  source_lines(source: string, from: number, to: number): {
+    start: number;
+    lines: string[];
+  } | undefined;
+  /** The original source LINE at a mapped position, trimmed and cut: what an anonymous callback
+   *  IS (`tags.map(async (tag) => {`), for a label a name cannot give. Undefined when the source
+   *  is not available. */
+  line_at_source(source: string, line: number, max?: number): string | undefined;
+  /** The function name written in the ORIGINAL source at a mapped position (1-based line and
+   *  column), for a frame whose map carries no name there: `function foo(`, a method `foo(` /
+   *  `#foo(` / `async foo(`, or an arrow assigned to `foo` (`const foo = () =>`, `foo: () =>`).
+   *  Undefined for a true anonymous callback. Reads the source through the same `read`. */
+  name_at_source(source: string, line: number, column: number): string | undefined;
+  /**
+   * A LINE OF A FUNCTION MATCHED BY TEXT that matched nothing itself (a build without maps: the
+   * build wrote `void 0`, folded a declaration into the next line, or wrapped one statement over
+   * several lines). From the nearest line above it that did match, within the function: still
+   * inside that statement (its brackets not yet closed) → that statement's line; else as far
+   * below it as in the build. Else from the function's own line. 0-based lines in, 1-based out.
+   */
+  text_nearby(url: string, line: number, fn_line: number): number | undefined;
+  /** A FUNCTION whose own line carries no mapping (Svelte leaves `function _page($$renderer…) {`
+   *  unmapped and maps the body from its next line to `+page.svelte`): the first mapped line of
+   *  its body, a few lines down. V8 places a function at its definition, so without this every
+   *  route component read as its built chunk. Generated code (ogygia's virtual modules) is not a
+   *  source anyone opens, and is left unmapped. */
+  resolve_body(url: string, line: number): {
+    source: string;
+    line: number;
+    column: number;
+    name?: string;
+    near_name?: string;
+    text?: true;
+  } | undefined;
+  resolve(url: string, line: number, column: number): {
+    source: string;
+    line: number;
+    column: number;
+    name?: string;
+    near_name?: string;
+    text?: true;
+  } | undefined;
+}
+/** Build a {@link SourceMapResolver} backed by `.map` files next to the chunks. */
+/** the module a built chunk's line belongs to (a build without maps), and whether it is the app's
+ *  own script module to match by text */
+export type ModuleAt = (path: string, line: number) => {
+  source: string;
+  text: boolean;
+} | undefined;
+export declare function sourcemap_resolver(read: (path: string) => string | undefined, module_at?: ModuleAt, opts?: {
+  any_ext?: boolean;
+}): SourceMapResolver;
+export declare function analyze(profile: CpuProfile, resolver?: SourceMapResolver, call_counts?: Record<string, number>, timeline_input?: TimelineInput, rename?: (name: string, url: string, stage: "frame" | "confirmed") => string | undefined, url_category?: (url: string, name: string, line: number) => FrameCategory | {
+  category: FrameCategory;
+  pkg?: string;
+} | undefined): Analysis;
+export interface HeapNode {
+  callFrame: CallFrame;
+  selfSize: number;
+  children?: HeapNode[];
+}
+export interface HeapAllocator {
+  name: string;
+  url: string;
+  line: number;
+  category: FrameCategory;
+  self_bytes: number;
+  total_bytes: number;
+}
+/**
+ * The renamer for a BROWSER profile: a component confirmed in a minified client chunk (Svelte's
+ * runtime is below it, so it is one, but its name is `Y`) is named after the `.svelte` files the
+ * build put in that chunk — `ProductCard`, or `ProductCard (+2 in chunk)` when the chunk holds
+ * several. `contents` is the build handoff's chunk summary by path (`chunkContents`). Only the
+ * confirmed stage renames: an unconfirmed `Pt` is a helper and stays app code.
+ */
+export declare function chunk_component_renamer(contents: (path: string) => readonly string[] | null | undefined): (name: string, url: string, stage: "frame" | "confirmed") => string | undefined;
+export declare function heap_by_component(head: HeapNode, limit?: number): {
+  name: string;
+  bytes: number;
+}[];
+export declare function analyze_heap(head: HeapNode, limit?: number): HeapAllocator[];
+export { another_routes_file, route_dirs, route_file_of };