@ogygia/devtools 0.0.0 → 0.11.0

package/dist/profiler/patterns.d.ts

@@ -0,0 +1,476 @@
+import { DocDiff } from "./doc-diff.js";
+import { FrameStat } from "./analyze.js";
+import { LedgerLine } from "./ledger.js";
+import { RetainedSite } from "./insights.js";
+import { AwaitEdge, AwaitNode } from "./timeline.js";
+import { SourceReader, tokens } from "./source-scan.js";
+export type PatternKind = "formatter-per-call" | "rescan-in-loop" | "lookup-in-loop" | "table-per-call" | "regexp-per-call" | "slow-regex" | "deep-copy" | "spread-accumulate" | "string-build" | "sort-per-call" | "date-parse" | "sync-io" | "yield-per-item" | "scan-for-key" | "library-per-item" | "waits-in-a-row" | "repeat-request" | "same-answer" | "almost-same-answer" | "kept-per-render" | "seed-whole-read" | "cache-never-hits" | "same-every-request" | "render-per-item" | "late-island-wait" | "batch-straggler" | "same-document" | "almost-same-document";
+/** a two-or-three-word tag for each kind, for a badge beside a line */
+export declare const PATTERN_LABEL: Record<PatternKind, string>;
+export interface PatternSite {
+  path: string;
+  file: string;
+  line: number;
+  /** a line of a built chunk: the source module it came from (see LedgerLine.module) */
+  module?: string;
+  code: string;
+  /** the function row this line belongs to (functions table key), when known */
+  fn?: string;
+  fn_name?: string;
+  /** same every request: every function the line calls — all of it leaves the request with the
+   *  line (`injectBadges(sitemapHtml(PRODUCTS))` takes both) */
+  moves?: string[];
+  cpu_ms: number;
+  alloc_bytes: number;
+  gc_ms: number;
+  /** how many times the function ran, when V8 counted it */
+  calls?: number;
+  /** the site sits inside a loop (a `for`, a `.map(`, an `{#each}`) */
+  in_loop: boolean;
+  /** CPU inside the libraries this line called (ledger `lib_ms`) */
+  lib_ms?: number;
+  /** those library functions, `name (pkg)` */
+  libs?: string[];
+  /** the site is inside a thin wrapper: the lines in ITS callers that call it (the place a cache
+   *  or a batch goes), each with whether that call runs in a loop */
+  via?: CallSite[];
+  /** a memory site: bytes it left alive after one more warm render */
+  kept_bytes?: number;
+  /** a memory site: some of it was kept INSIDE this package, which the line calls */
+  mem_via?: string;
+  /** a cache site: how many of the function's calls the cache answered */
+  hits?: number;
+  /** a same-answer site: the size of the answer that came back unchanged every render */
+  answer_bytes?: number;
+  /** a same-answer site whose requests carried who is asking (cookie / authorization): cache per user */
+  personal?: boolean;
+  /** a same-answer site: what the service's own Cache-Control allows (seconds to keep a copy; not to
+   *  store it at all; one user's) */
+  upstream_cache?: CacheRules;
+  /** the change, written out: these exact lines, and what to put in their place (a waits-in-a-row
+   *  chain of plain one-line awaits, proven independent, as one Promise.all) */
+  rewrite?: {
+    file: string;
+    line: number;
+    before: string;
+    after: string;
+  };
+  /** a memory site the growth check measured: still growing every render, or flat after one */
+  grows?: boolean;
+  /** a waiting site: the ms its calls waited in a row */
+  wait_ms?: number;
+  /** a waiting site: what it waited on (`GET api.shop.test/stock/:id`, `file read`) */
+  target?: string;
+  /** the code around the site (two lines each side), so the loop or the value it uses shows */
+  context?: {
+    start: number;
+    lines: string[];
+  };
+}
+export interface CallSite {
+  path: string;
+  file: string;
+  line: number;
+  /** a line of a built chunk: the source module it came from (see LedgerLine.module) */
+  module?: string;
+  code: string;
+  /** the calling function (functions table key) */
+  fn?: string;
+  in_loop: boolean;
+}
+export interface Pattern {
+  kind: PatternKind;
+  /** what is happening, in plain words */
+  title: string;
+  /** what to do about it */
+  fix: string;
+  /** a tiny before → after, when one says it better than words */
+  example?: {
+    before: string;
+    after: string;
+  };
+  sites: PatternSite[];
+  /** the measured cost on the sites: CPU plus the GC their allocations caused */
+  cost_ms: number;
+  /** bytes the sites allocated */
+  alloc_bytes: number;
+  /** a rough estimate of the ms a fix gives back (a share of cost_ms that depends on the kind) */
+  save_ms: number;
+  /** the numbers behind it, one line */
+  evidence: string;
+  /** the cost is WAITING (calls in a row), not CPU: `cost_ms` / `save_ms` are wall-clock waits */
+  wait?: boolean;
+  /** the cost is MEMORY kept alive after a render: `kept_bytes` is it, and there is no time saving */
+  kept_bytes?: number;
+  /** a memory pattern: requests left before the heap is full at this rate (from the heap's room now) */
+  requests_left?: number;
+  /** a memory pattern the growth check measured: it kept climbing, or it levelled off */
+  growth?: "grows" | "levels-off";
+  /** a size pattern (ogygia's page seed): the bytes it makes ship with every page view */
+  seed_bytes?: number;
+  /** waits in a row: each site's chain, its calls in order on the recording's clock */
+  chains?: {
+    start: number;
+    ms: number;
+  }[][];
+  /** waits in a row: the saving the simple sum promised (every wait but the longest), kept when the
+   *  critical-path check cut `save_ms` below it */
+  naive_save_ms?: number;
+}
+/**
+ * THE CRITICAL PATH, not the sum: a chain of waits started together ends when its longest call
+ * does, but the render goes on only once whatever ran BESIDE the chain is done too (Kit waits for
+ * a layout load running alongside a page load; a Promise.all waits for all). So the time that
+ * really comes off is the chain's end minus the later of its new end and the end (up to the old
+ * chain end) of any call that overlapped it. Only calls that overlapped count: a call that started
+ * after the chain ended comes later and moves up with it, it is not beside it. Each chain call is
+ * found in the render's await graph by its start and length; undefined when the graph does not
+ * hold the chains (another window, a capped graph).
+ */
+export declare function wait_save_on_path(p: Pick<Pattern, "chains">, awaits: {
+  nodes: AwaitNode[];
+  edges: AwaitEdge[];
+} | undefined, _window_ms: number, w0: number): {
+  save_ms: number;
+  bound_by?: string;
+} | undefined;
+/**
+ * THE SAME ANSWER EVERY TIME: the GET calls that ran in EVERY profiled render and got the same bytes
+ * back each time (the body fingerprint net.ts takes). Across requests the render asks for data that
+ * did not change: an answer to cache (a CMS entry, a config, a price list, flags). Keyed like a
+ * wait's `exact` (`GET <url>`). Needs two renders or more; a call whose body was not read (no
+ * fingerprint) or that failed never counts.
+ */
+export declare function stable_answers(calls: readonly {
+  method: string;
+  url: string;
+  status: number;
+  start: number;
+  body_hash?: string;
+}[], runs: readonly {
+  start: number;
+  end: number;
+}[]): Set<string>;
+/** the GETs made in EVERY render whose answers were NOT the same bytes each time (`GET <url>`):
+ *  the candidates for "almost the same answer" (net.ts `answer_diff` says how little changed) */
+export declare function varied_answers(calls: readonly {
+  method: string;
+  url: string;
+  status: number;
+  start: number;
+  body_hash?: string;
+}[], runs: readonly {
+  start: number;
+  end: number;
+}[]): Set<string>;
+/**
+ * THE SAME ANSWER, EVERY RENDER — the pattern: the calls of one render whose exact request (`stable`,
+ * from `stable_answers`) answered the same bytes in every profiled render. Each place that makes one
+ * is listed with what it waits, how big the answer is, and the line to cache at. The saving is what
+ * comes off the render when the calls are answered from a cache: each one's end moves to its start,
+ * except where another call (not cached) overlapped it and still sets the end — read off the
+ * render's await graph when it holds the calls, else each call's own wait.
+ */
+export declare function find_same_answers(input: {
+  calls: readonly WaitCall[];
+  stable: ReadonlySet<string>;
+  source?: SourceReader;
+  awaits?: {
+    nodes: AwaitNode[];
+    edges: AwaitEdge[];
+  };
+  w0?: number;
+  /** ALMOST the same: the answers that differed between renders only in a small stretch, with that
+   *  stretch (`GET <url>` → text): the same cache, minus the part that changes */
+  almost?: ReadonlyMap<string, string>;
+}): Pattern | undefined;
+export interface PatternInput {
+  ledger: readonly LedgerLine[];
+  functions: readonly FrameStat[];
+  /** lines `from`..`to` of a source file (1-based, inclusive), untrimmed */
+  source?: SourceReader;
+  /** how many renders the profile's CPU numbers add up (page mode's runs), for the wording */
+  renders?: number;
+  /** the V8 heap's limit and what is in use now, for a leak's countdown; `function`: the ceiling
+   *  is the serverless function's memory size (AWS Lambda), smaller than the heap, and what is in
+   *  use is the process's resident memory */
+  heap?: {
+    limit_bytes: number;
+    used_bytes: number;
+    function?: boolean;
+  };
+  /** a few more renders with a collection after each: confirms a leak, or shows it levels off */
+  growth?: HeapGrowth;
+}
+/** Where the LAST line of `lines` (a function's body, from its first line) runs in a loop: the
+ *  token index on that line from which code is inside one. 0 when the whole line is (an enclosing
+ *  loop body), the index after a loop header on the line itself (`for (…) x = f(x)`, `xs.map(`),
+ *  -1 when none of it is. Tracks brace blocks: a block opened after a loop header (`for`, `while`,
+ *  `do`, a `.map(` / `.forEach(` callback) is a loop body. A Svelte file counts `{#each}` too. */
+export declare function loop_from(lines: readonly string[], svelte?: boolean): number;
+/** Does any of the last line of `lines` run inside a loop? (`loop_from` ≥ 0) */
+export declare const in_loop: (lines: readonly string[], svelte?: boolean) => boolean;
+/**
+ * SYNC I/O TOO QUICK TO SAMPLE: a small file read on every request finishes under the CPU
+ * sampler's interval, so no sample lands on it, yet it blocks every other request on the server
+ * while the disk answers (a cold disk or a bigger file makes it long). V8's call counts (the
+ * coverage render) count Node's own `readFileSync` like any function: a *Sync call counted in the
+ * render, at a line of the route's own files inside a function the render ran (counted too), is
+ * one. Module top-level code runs once at start-up and is left out. Pure: the counts and the files'
+ * text in, the pattern out (undefined when nothing qualifies). No regex.
+ */
+export declare function counted_sync_io(counts: Readonly<Record<string, number>>, files: readonly {
+  path: string;
+  file: string;
+  text: string;
+}[]): Pattern | undefined;
+export declare function find_patterns(input: PatternInput): Pattern[];
+/** one finished wait, from the network log or the I/O log */
+export interface WaitCall {
+  start: number;
+  /** the whole wait: headers + body for a fetch, init → destroy for an I/O resource */
+  ms: number;
+  /** what it waited on, as a group label (`GET api.shop.test/stock/:id`, `file read`) */
+  target: string;
+  /** the app line that made the call */
+  at?: {
+    path: string;
+    line: number;
+  };
+  /** the line that called THAT function, when the call sits in a helper (`fetchStock`) */
+  outer?: {
+    path: string;
+    line: number;
+  };
+  /** the page it served (calls of different requests never chain) */
+  scope?: string | null;
+  /** the exact request, for a read (`GET https://api/session?x=1`): two with the same one in a render
+   *  asked for the same answer. Absent for writes, whose repeats can be on purpose. */
+  exact?: string;
+  /** the decoded body size, when read */
+  bytes?: number;
+  /** the request carried a cookie or an authorization header (its answer may be per user) */
+  personal?: boolean;
+  /** the answer's own `Cache-Control`, as the service sent it */
+  cache?: string;
+}
+export type CacheRules = {
+  max_age?: number;
+  no_store?: boolean;
+  no_cache?: boolean;
+  private?: boolean;
+};
+/** What a service's `Cache-Control` allows: how long a copy may be kept (s-maxage over max-age, for
+ *  a shared cache), whether it must not be stored, must be checked with the service before every
+ *  reuse (`no-cache`, or a max-age of 0), or is one user's. Split by hand, no regex. */
+export declare function cache_rules(header: string | undefined): CacheRules | undefined;
+export interface WaitInput {
+  calls: readonly WaitCall[];
+  source?: SourceReader;
+}
+/**
+ * THE WAITS IN A ROW: calls made from ONE line whose waits did not overlap — each started after
+ * the one before it ended — so the line waited for them one by one (`for (…) await fetch(…)`).
+ * Measured, not guessed: the sum of the waits is what the line cost in wall time, the longest
+ * one is about what it would cost if they ran together, and the difference is the saving.
+ */
+export declare function find_wait_patterns(input: WaitInput): Pattern[];
+export interface FixImpact {
+  /** estimated CPU a fix of every pattern gives back, ms */
+  cpu_ms: number;
+  /** estimated waiting it gives back, ms */
+  wait_ms: number;
+  /** the render it is measured against (median of the runs), ms */
+  render_ms: number;
+  /** the render after the fixes, about; never below a tenth of today's */
+  after_ms: number;
+  /** share of the render the fixes take off, 0..90 */
+  pct: number;
+}
+/** "Fix these and the render goes from 754 ms to ~300 ms." Each costly line belongs to one pattern,
+ *  so the savings add without counting a line twice; the sum is capped at 90 % of the render (an
+ *  estimate never promises a free page). Undefined without a render to measure against.
+ *
+ *  UNITS: a CPU pattern's numbers add up the whole recording — `renders` renders in page mode —
+ *  while a waiting pattern is measured on ONE render (the network log is scoped to one run). CPU
+ *  savings are divided by `renders` so both are per render, like `render_ms`. */
+export declare function fix_impact(patterns: readonly Pick<Pattern, "save_ms" | "wait">[], render_ms: number, renders?: number, wait_ms?: number): FixImpact | undefined;
+export interface HeapGrowth {
+  /** renders measured (each followed by a full collection) */
+  renders: number;
+  /** used heap after the first collection, and after the last render's */
+  start_bytes: number;
+  end_bytes: number;
+  /** average growth per render */
+  per_render_bytes: number;
+  /** the second half of the renders grew far less than the first: a bounded cache filling up */
+  levels_off: boolean;
+  /** the used heap after each collection, MB */
+  series_mb: number[];
+  /** what each allocation line still held after all the renders (a live sample across them) */
+  sites?: RetainedSite[];
+  /** the same sampler read halfway (after `half_renders`): a leaking line grows from it in step */
+  half_renders?: number;
+  half_sites?: RetainedSite[];
+}
+/** A leak grows the same every render; a cache with a size limit grows, then stops. The second
+ *  half's rate against the first half's tells them apart; under 64 KB a render is flat either way. */
+/** A growth series (the settled heap before, then after each render) that is FLAT: under 32 KB a
+ *  render (half of `heap_growth`'s line), and every settled reading after the first render within
+ *  256 KB of the others — more renders could not make it grow, so the check may stop. */
+export declare function is_flat(series: readonly number[]): boolean;
+/** A LEAK PAST DOUBT after three renders: each kept 16 MB or more, the largest step at most half again
+ *  the smallest — steady growth no further render can turn into "it levels off", and each more render
+ *  takes that much of the measured server's heap (/hell: 70 MB a render, six renders, 9 s and 420 MB
+ *  of the instance's memory for a verdict the first three gave). A smaller leak keeps the full check:
+ *  its halfway read is what tells a growing line from a bounded cache still filling. */
+export declare function is_clear_leak(series: readonly number[]): boolean;
+export declare function heap_growth(series: readonly number[]): HeapGrowth | undefined;
+export interface WholeReader {
+  /** the component, as the page names it */
+  name: string;
+  /** its file (for display and the row) */
+  file: string;
+  line: number;
+  code: string;
+  context?: {
+    start: number;
+    lines: string[];
+  };
+}
+/**
+ * THE SEED SHIPS WHOLE BECAUSE OF A LINE: an island that takes `page.data` whole (a spread, a
+ * pass-through, `const d = page.data`) makes every key ship to the browser, in every page view.
+ * The seed explainer knew WHICH islands; this points at the line in each that does it, with the
+ * bytes it costs. A size, not a time: no saving in ms is claimed.
+ */
+export declare function seed_whole_pattern(readers: readonly WholeReader[], seed_bytes: number, top?: {
+  key: string;
+  bytes: number;
+}): Pattern | undefined;
+export interface ConstantWork {
+  path: string;
+  file: string;
+  line: number;
+  code: string;
+  /** what the line names (`valid`) and the functions it runs */
+  names: string[];
+  calls: string[];
+  /** CPU the line and its functions took, over every profiled render (ms) */
+  cpu_ms: number;
+  context?: PatternSite["context"];
+}
+/**
+ * THE SAME WORK EVERY REQUEST: load lines whose value depends only on the module (source-scan
+ * `constant_work`), with the CPU they took. The CPU twin of `same-answer`: every request computes
+ * the same result again. Saving: all of it (computed once, at module load or on first use).
+ */
+export declare function same_work_pattern(work: readonly ConstantWork[], renders: number): Pattern | undefined;
+export interface PerItemRender {
+  /** the component rendered once per item, its renders in one render of the page and its time
+   *  over every profiled render */
+  component: string;
+  instances: number;
+  total_ms: number;
+  /** the `{#each}` that renders it */
+  each: {
+    path: string;
+    file: string;
+    line: number;
+    code: string;
+    context?: PatternSite["context"];
+  };
+  /** the page-data key the loop walks, and the load line that makes it */
+  key?: string;
+  made_at?: {
+    path: string;
+    file: string;
+    line: number;
+    code: string;
+  };
+}
+/**
+ * A COMPONENT RENDERED ONCE PER ITEM: its render count (V8's count of one render) comes from an
+ * `{#each}` over a page-data key, and that key is made on one load line (source). The chain says
+ * where its time is decided: render fewer items (a page of them, a smaller slice), or make each
+ * one cheaper. The cost scales with the count, so no saving is claimed: it is the lever, not a fix.
+ */
+export declare function render_per_item_pattern(items: readonly PerItemRender[], renders: number): Pattern | undefined;
+/**
+ * THE SAME DOCUMENT EVERY REQUEST: every profiled render returned the same bytes, and nothing it
+ * reads is the visitor's (no load takes cookies, locals or the raw request; no outbound call carried
+ * a cookie or an authorization header). The whole render can be skipped: a CDN keeps the document
+ * (`Cache-Control: s-maxage`, keyed by its URL), or ogygia's postrender stores it. Saving: the
+ * render itself.
+ */
+export declare function same_document_pattern(input: {
+  file: string;
+  render_ms: number;
+  bytes: number;
+  code?: string;
+  /** what the response says that no shared cache accepts: a Set-Cookie, Cache-Control private / no-store */
+  blocked?: {
+    cookie?: boolean;
+    cache_control?: string;
+  };
+}): Pattern;
+/**
+ * THE SAME PAGE BUT FOR A FEW PARTS: the renders' documents differ only in a few small groups (an
+ * island's props, an id stamped per render, numbered comment markers) and nothing read is the
+ * visitor's. Those parts are all that stands between the page and a cached copy: make them stop
+ * changing (an id derived from the data, not a counter or a random; a live value fetched in the
+ * browser or in a deferred region) and the whole render comes off.
+ */
+export declare function almost_same_document_pattern(input: {
+  file: string;
+  render_ms: number;
+  diff: DocDiff;
+  code?: string;
+}): Pattern;
+export interface LateIslandWait {
+  /** the wait (`GET api/reviews`), one render: its ms and the part nothing else was in flight */
+  call: string;
+  ms: number;
+  alone: number;
+  /** the load line that made it */
+  at: {
+    path: string;
+    file: string;
+    line: number;
+    code: string;
+  };
+  /** the key it fills, and the late island that alone uses it (where) */
+  key: string;
+  island: string;
+  wake: string;
+  use: {
+    path: string;
+    file: string;
+    line: number;
+    code: string;
+  };
+}
+/**
+ * THE PAGE WAITS FOR A LATE ISLAND'S DATA: a call whose every key is used only as props of an island
+ * that wakes late (`visible`, `idle`, `interaction`). Every request waits for it before the first
+ * byte, for markup the visitor may never scroll to. Deferred (`render: 'deferred'`), the island
+ * renders on the server when it wakes, with its own call: the page stops waiting. Saving: the
+ * stretch the call held the render alone.
+ */
+export declare function late_island_pattern(items: readonly LateIslandWait[]): Pattern | undefined;
+export interface ColdCacheInput {
+  functions: readonly FrameStat[];
+  /** V8's call counts from the coverage render: `<name>\0<script url>` → calls */
+  call_counts: Readonly<Record<string, number>>;
+  source: SourceReader;
+}
+/**
+ * THE CACHE THAT NEVER HITS: an app function with a memo shape — a lookup (`M.get(k)`,
+ * `M.has(k)`), an early `return` of the hit, and a store (`M.set(k, …)`) after the work — whose
+ * MISS PATH ran about as often as the function itself. Measured from V8's call counts, which
+ * survive inlining: a helper the miss path calls once (not in a loop), and nothing else calls,
+ * ran once per miss; its count against the memo's is the miss rate. (Block counts would say it
+ * directly, but V8 only instruments functions compiled after they are switched on.)
+ */
+export declare function find_cold_caches(input: ColdCacheInput): Pattern | undefined;
+export { tokens };