@reicek/neataptic-ts 0.1.24 → 0.1.26

package/scripts/analyze-trace/analyze-trace.io.ts

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+
+import { DEFAULT_TOP_COUNT } from './analyze-trace.constants.js';
+import type { CliOptions, TraceFile } from './analyze-trace.types.js';
+
+/**
+ * Resolves CLI flags for one trace-analyzer invocation.
+ *
+ * Supported inputs:
+ * - positional trace path
+ * - `--top=NUMBER`
+ * - `--top NUMBER`
+ *
+ * @param argumentValues - CLI arguments after the script path.
+ * @returns Parsed CLI options.
+ */
+export function resolveCliOptions(
+  argumentValues: readonly string[],
+): CliOptions {
+  const pathArgument = argumentValues.find(
+    (argument) => !argument.startsWith('--'),
+  );
+  if (!pathArgument) {
+    throw new Error(
+      'Missing trace path. Example: npm run trace:analyze -- test/examples/flappy_bird/Trace.json',
+    );
+  }
+
+  return {
+    tracePath: pathArgument,
+    topCount: resolveRequestedTopCount(argumentValues),
+  };
+}
+
+/**
+ * Reads and parses one trace JSON file.
+ *
+ * @param traceFilePath - Absolute or relative trace file path.
+ * @returns Parsed trace file payload.
+ */
+export function loadTrace(traceFilePath: string): TraceFile {
+  const traceFileContents = fs.readFileSync(traceFilePath, 'utf8');
+  return JSON.parse(traceFileContents) as TraceFile;
+}
+
+/**
+ * Resolves the requested top-count override from CLI flags.
+ *
+ * @param argumentValues - CLI arguments after the script path.
+ * @returns Positive top-count value or the repo default.
+ */
+function resolveRequestedTopCount(argumentValues: readonly string[]): number {
+  const inlineTopArgument = argumentValues.find((argument) =>
+    argument.startsWith('--top='),
+  );
+  const splitTopArgumentIndex = argumentValues.findIndex(
+    (argument) => argument === '--top',
+  );
+
+  const requestedTopCount = inlineTopArgument
+    ? Number.parseInt(inlineTopArgument.slice('--top='.length), 10)
+    : splitTopArgumentIndex >= 0
+      ? Number.parseInt(argumentValues[splitTopArgumentIndex + 1] ?? '', 10)
+      : DEFAULT_TOP_COUNT;
+
+  return Number.isFinite(requestedTopCount) && requestedTopCount > 0
+    ? requestedTopCount
+    : DEFAULT_TOP_COUNT;
+}

package/scripts/analyze-trace/analyze-trace.report.ts

@@ -0,0 +1,100 @@
+import { formatDistribution, formatMs } from './analyze-trace.shared.js';
+import type { TraceAnalysis } from './analyze-trace.types.js';
+
+/**
+ * Builds the textual report lines for one analyzed trace.
+ *
+ * @param traceAnalysis - Fully analyzed trace payload.
+ * @returns Report lines in display order.
+ */
+export function buildTraceReportLines(traceAnalysis: TraceAnalysis): string[] {
+  const reportLines: string[] = [];
+
+  appendSection(reportLines, 'Trace', [
+    `File: ${traceAnalysis.traceFilePath}`,
+    `Window: ${formatMs(traceAnalysis.timeRange.windowMs)} across ${traceAnalysis.traceEventCount.toLocaleString()} events`,
+    `Frames: ${traceAnalysis.beginFrameCount.toLocaleString()} begin, ${traceAnalysis.droppedFrameCount.toLocaleString()} dropped`,
+  ]);
+
+  appendSection(
+    reportLines,
+    'Thread Summary',
+    traceAnalysis.threadSummaries.map(
+      (threadSummary) =>
+        `${threadSummary.label}: total=${formatMs(threadSummary.totalDurationMs)}, ` +
+        `RunTask=${formatMs(threadSummary.runTaskDurationMs)}, ` +
+        `>16.7ms=${threadSummary.longTaskCount16ms}, ` +
+        `>50ms=${threadSummary.longTaskCount50ms}, ` +
+        `max=${formatMs(threadSummary.maxTaskMs)}`,
+    ),
+  );
+
+  appendSection(reportLines, 'Animation Frames', [
+    `FireAnimationFrame: ${formatDistribution(traceAnalysis.fireAnimationFrameDurations)}`,
+    `FunctionCall: ${formatDistribution(traceAnalysis.functionCallDurations)}`,
+  ]);
+
+  appendSection(
+    reportLines,
+    'Longest Events',
+    traceAnalysis.longestEvents.map(
+      (longEvent) =>
+        `${formatMs(longEvent.durationMs)} | ${longEvent.threadLabel} | ${longEvent.eventName}${
+          longEvent.scriptUrl ? ` | ${longEvent.scriptUrl}` : ''
+        }`,
+    ),
+  );
+
+  appendSection(
+    reportLines,
+    'Top Events',
+    traceAnalysis.hottestEvents.map(
+      (eventSummary) =>
+        `${eventSummary.name}: count=${eventSummary.count.toLocaleString()}, total=${formatMs(eventSummary.totalMs)}, max=${formatMs(eventSummary.maxMs)}`,
+    ),
+  );
+
+  appendSection(
+    reportLines,
+    'Top Function Calls',
+    traceAnalysis.hottestFunctionCalls.map(
+      (functionCallSummary) =>
+        `${functionCallSummary.name}: count=${functionCallSummary.count.toLocaleString()}, total=${formatMs(functionCallSummary.totalMs)}, max=${formatMs(functionCallSummary.maxMs)}`,
+    ),
+  );
+
+  return reportLines;
+}
+
+/**
+ * Prints one analyzed trace report to stdout.
+ *
+ * @param traceAnalysis - Fully analyzed trace payload.
+ * @returns Nothing.
+ */
+export function printTraceReport(traceAnalysis: TraceAnalysis): void {
+  for (const reportLine of buildTraceReportLines(traceAnalysis)) {
+    console.log(reportLine);
+  }
+}
+
+/**
+ * Appends one report section to the output line buffer.
+ *
+ * @param reportLines - Mutable output line buffer.
+ * @param title - Section title.
+ * @param contentLines - Section body lines.
+ * @returns Nothing.
+ */
+function appendSection(
+  reportLines: string[],
+  title: string,
+  contentLines: readonly string[],
+): void {
+  if (reportLines.length > 0) {
+    reportLines.push('');
+  }
+
+  reportLines.push(`[${title}]`);
+  reportLines.push(...contentLines);
+}

package/scripts/analyze-trace/analyze-trace.shared.ts

@@ -0,0 +1,116 @@
+import type { Primitive } from './analyze-trace.types.js';
+
+/**
+ * Safely resolves a nested primitive value from a trace event args object.
+ *
+ * @param value - Candidate object tree.
+ * @param pathSegments - Nested path segments to follow.
+ * @returns Primitive value when the path resolves cleanly.
+ */
+export function readNestedPrimitive(
+  value: unknown,
+  pathSegments: readonly string[],
+): Primitive {
+  let currentValue: unknown = value;
+
+  for (const pathSegment of pathSegments) {
+    if (!currentValue || typeof currentValue !== 'object') {
+      return undefined;
+    }
+
+    currentValue = (currentValue as Record<string, unknown>)[pathSegment];
+  }
+
+  if (
+    currentValue == null ||
+    typeof currentValue === 'string' ||
+    typeof currentValue === 'number' ||
+    typeof currentValue === 'boolean'
+  ) {
+    return currentValue;
+  }
+
+  return undefined;
+}
+
+/**
+ * Formats a duration in milliseconds for stable textual output.
+ *
+ * @param durationMs - Duration in milliseconds.
+ * @returns Fixed two-decimal duration string.
+ */
+export function formatMs(durationMs: number): string {
+  return `${durationMs.toFixed(2)}ms`;
+}
+
+/**
+ * Computes a nearest-rank percentile from an already sorted numeric array.
+ *
+ * @param sortedDurations - Sorted numeric sample set.
+ * @param rank - Percentile rank in the inclusive range `[0, 1]`.
+ * @returns Percentile value or `0` when the list is empty.
+ */
+export function percentile(
+  sortedDurations: readonly number[],
+  rank: number,
+): number {
+  if (sortedDurations.length === 0) {
+    return 0;
+  }
+
+  const clampedRank = Math.max(0, Math.min(1, rank));
+  const index = Math.min(
+    sortedDurations.length - 1,
+    Math.floor(clampedRank * (sortedDurations.length - 1)),
+  );
+
+  return sortedDurations[index];
+}
+
+/**
+ * Formats a compact percentile summary for one ascending-sorted duration collection.
+ *
+ * @param sortedDurationsMs - Ascending-sorted duration samples in milliseconds.
+ * @returns Human-readable summary string.
+ */
+export function formatDistribution(
+  sortedDurationsMs: readonly number[],
+): string {
+  if (sortedDurationsMs.length === 0) {
+    return 'count=0';
+  }
+
+  return [
+    `count=${sortedDurationsMs.length.toLocaleString()}`,
+    `p50=${formatMs(percentile(sortedDurationsMs, 0.5))}`,
+    `p90=${formatMs(percentile(sortedDurationsMs, 0.9))}`,
+    `p99=${formatMs(percentile(sortedDurationsMs, 0.99))}`,
+    `max=${formatMs(sortedDurationsMs.at(-1) ?? 0)}`,
+  ].join(', ');
+}
+
+/**
+ * Creates a stable lookup key for one process id.
+ *
+ * @param pid - Process identifier from the trace.
+ * @returns Stable process key when the id exists.
+ */
+export function createProcessKey(pid: number | undefined): string | undefined {
+  return typeof pid === 'number' ? `pid:${pid}` : undefined;
+}
+
+/**
+ * Creates a stable lookup key for one process/thread pair.
+ *
+ * @param pid - Process identifier from the trace.
+ * @param tid - Thread identifier from the trace.
+ * @returns Stable thread key when both ids exist.
+ */
+export function createThreadKey(
+  pid: number | undefined,
+  tid: number | undefined,
+): string | undefined {
+  return typeof pid === 'number' && typeof tid === 'number'
+    ? `pid:${pid}:tid:${tid}`
+    : undefined;
+}

package/scripts/analyze-trace/analyze-trace.ts

@@ -0,0 +1,45 @@
+/**
+ * Reads a Chrome or Perfetto trace export and prints a compact performance
+ * report.
+ *
+ * The entrypoint stays intentionally small: CLI parsing, trace loading,
+ * analysis, and report rendering each live in focused sibling modules.
+ *
+ * Usage:
+ *   npm run trace:analyze -- test/examples/flappy_bird/Trace-20260309T191949.json
+ *   npm run docs:build-scripts && node dist-docs/scripts/analyze-trace/analyze-trace.js path/to/trace.json --top=20
+ */
+import path from 'node:path';
+
+import { analyzeTraceEvents } from './analyze-trace.analysis.js';
+import { loadTrace, resolveCliOptions } from './analyze-trace.io.js';
+import { printTraceReport } from './analyze-trace.report.js';
+
+/**
+ * CLI entry point.
+ *
+ * @returns Nothing.
+ */
+function main(): void {
+  // Step 1: Resolve the CLI request and load the raw trace.
+  const cliOptions = resolveCliOptions(process.argv.slice(2));
+  const traceFilePath = path.resolve(cliOptions.tracePath);
+  const traceFile = loadTrace(traceFilePath);
+  const traceEvents = traceFile.traceEvents ?? [];
+
+  if (traceEvents.length === 0) {
+    throw new Error(`Trace contains no events: ${traceFilePath}`);
+  }
+
+  // Step 2: Derive deterministic report data from the raw trace.
+  const traceAnalysis = analyzeTraceEvents({
+    traceFilePath,
+    traceEvents,
+    topCount: cliOptions.topCount,
+  });
+
+  // Step 3: Render the final textual report.
+  printTraceReport(traceAnalysis);
+}
+
+main();

package/scripts/analyze-trace/analyze-trace.types.ts

@@ -0,0 +1,72 @@
+/** Primitive trace metadata value supported by the nested args reader. */
+export type Primitive = string | number | boolean | null | undefined;
+
+/** Minimal Chrome or Perfetto trace event shape used by the analyzer. */
+export interface TraceEvent {
+  pid?: number;
+  tid?: number;
+  ts?: number;
+  dur?: number;
+  tdur?: number;
+  ph?: string;
+  cat?: string;
+  name?: string;
+  args?: Record<string, unknown>;
+}
+
+/** Top-level trace file shape expected from exported JSON captures. */
+export interface TraceFile {
+  traceEvents?: TraceEvent[];
+}
+
+/** Parsed CLI options for one analyzer invocation. */
+export interface CliOptions {
+  tracePath: string;
+  topCount: number;
+}
+
+/** Summary metrics for one thread label in the trace. */
+export interface ThreadSummary {
+  label: string;
+  totalDurationMs: number;
+  runTaskDurationMs: number;
+  longTaskCount16ms: number;
+  longTaskCount50ms: number;
+  maxTaskMs: number;
+}
+
+/** Aggregated duration rollup for one trace event or one script URL. */
+export interface AggregatedDuration {
+  name: string;
+  count: number;
+  totalMs: number;
+  maxMs: number;
+}
+
+/** Longest single complete event entry used by the report. */
+export interface LongEventSummary {
+  durationMs: number;
+  threadLabel: string;
+  eventName: string;
+  scriptUrl?: string;
+}
+
+/** Visible trace window spanned by the capture. */
+export interface TraceTimeRange {
+  windowMs: number;
+}
+
+/** Fully analyzed trace payload used by the reporting layer. */
+export interface TraceAnalysis {
+  traceFilePath: string;
+  traceEventCount: number;
+  timeRange: TraceTimeRange;
+  droppedFrameCount: number;
+  beginFrameCount: number;
+  threadSummaries: ThreadSummary[];
+  hottestEvents: AggregatedDuration[];
+  hottestFunctionCalls: AggregatedDuration[];
+  longestEvents: LongEventSummary[];
+  fireAnimationFrameDurations: number[];
+  functionCallDurations: number[];
+}

package/scripts/assets/theme.css

@@ -22,14 +22,11 @@
   --double-border: 3px double rgba(15, 181, 255, 0.88);
   --double-border-soft: 3px double rgba(10, 142, 160, 0.58);
   --panel-glow:
-    inset 0 0 0 1px rgba(15, 181, 255, 0.16),
-    0 0 18px rgba(15, 181, 255, 0.12);
+    inset 0 0 0 1px rgba(15, 181, 255, 0.16), 0 0 18px rgba(15, 181, 255, 0.12);
   --panel-glow-strong:
-    inset 0 0 0 1px rgba(15, 181, 255, 0.2),
-    0 0 24px rgba(0, 229, 255, 0.15);
+    inset 0 0 0 1px rgba(15, 181, 255, 0.2), 0 0 24px rgba(0, 229, 255, 0.15);
   --focus-ring:
-    0 0 0 2px rgba(255, 154, 46, 0.9),
-    0 0 0 5px rgba(15, 181, 255, 0.2);
+    0 0 0 2px rgba(255, 154, 46, 0.9), 0 0 0 5px rgba(15, 181, 255, 0.2);
 }
 * {
   box-sizing: border-box;
@@ -60,13 +57,35 @@ body::before {
   inset: 0;
   pointer-events: none;
   background:
-    radial-gradient(circle at 12% 18%, rgba(255, 255, 255, 0.2) 0 1px, transparent 1.5px),
-    radial-gradient(circle at 78% 12%, rgba(159, 220, 255, 0.18) 0 1px, transparent 1.5px),
-    radial-gradient(circle at 68% 42%, rgba(0, 229, 255, 0.14) 0 1px, transparent 1.5px),
-    radial-gradient(circle at 28% 72%, rgba(255, 255, 255, 0.12) 0 1px, transparent 1.5px),
+    radial-gradient(
+      circle at 12% 18%,
+      rgba(255, 255, 255, 0.2) 0 1px,
+      transparent 1.5px
+    ),
+    radial-gradient(
+      circle at 78% 12%,
+      rgba(159, 220, 255, 0.18) 0 1px,
+      transparent 1.5px
+    ),
+    radial-gradient(
+      circle at 68% 42%,
+      rgba(0, 229, 255, 0.14) 0 1px,
+      transparent 1.5px
+    ),
+    radial-gradient(
+      circle at 28% 72%,
+      rgba(255, 255, 255, 0.12) 0 1px,
+      transparent 1.5px
+    ),
     linear-gradient(rgba(10, 142, 160, 0.05) 1px, transparent 1px),
     linear-gradient(90deg, rgba(10, 142, 160, 0.04) 1px, transparent 1px);
-  background-size: auto, auto, auto, auto, 100% 28px, 28px 100%;
+  background-size:
+    auto,
+    auto,
+    auto,
+    auto,
+    100% 28px,
+    28px 100%;
   opacity: 0.45;
   z-index: -1;
 }
@@ -89,8 +108,11 @@ a:focus-visible {
   position: sticky;
   top: 0;
   z-index: 30;
-  background:
-    linear-gradient(180deg, rgba(0, 0, 0, 0.96), rgba(3, 8, 18, 0.94));
+  background: linear-gradient(
+    180deg,
+    rgba(0, 0, 0, 0.96),
+    rgba(3, 8, 18, 0.94)
+  );
   backdrop-filter: blur(8px);
   border-bottom: var(--double-border-soft);
   box-shadow:
@@ -225,7 +247,11 @@ a:focus-visible {
   max-height: calc(100vh - 90px);
   overflow: auto;
   background:
-    radial-gradient(circle at top left, rgba(0, 229, 255, 0.08), transparent 36%),
+    radial-gradient(
+      circle at top left,
+      rgba(0, 229, 255, 0.08),
+      transparent 36%
+    ),
     linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
   border: var(--double-border);
   border-radius: 0;
@@ -281,14 +307,21 @@ a:focus-visible {
   position: relative;
   padding: 12px;
   border: var(--double-border-soft);
-  background:
-    linear-gradient(180deg, rgba(3, 17, 31, 0.96), rgba(0, 0, 0, 0.98));
+  background: linear-gradient(
+    180deg,
+    rgba(3, 17, 31, 0.96),
+    rgba(0, 0, 0, 0.98)
+  );
   box-shadow: var(--panel-glow);
 }
 .group-priority {
   padding: 12px;
   background:
-    radial-gradient(circle at top left, rgba(255, 154, 46, 0.08), transparent 34%),
+    radial-gradient(
+      circle at top left,
+      rgba(255, 154, 46, 0.08),
+      transparent 34%
+    ),
     linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
   border: var(--double-border);
   box-shadow: var(--panel-glow-strong);
@@ -318,7 +351,11 @@ a:focus-visible {
   border-radius: 0;
   border: var(--double-border-soft);
   background:
-    radial-gradient(circle at top left, rgba(0, 229, 255, 0.08), transparent 40%),
+    radial-gradient(
+      circle at top left,
+      rgba(0, 229, 255, 0.08),
+      transparent 40%
+    ),
     linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
   box-shadow: var(--panel-glow);
 }
@@ -432,7 +469,11 @@ a:focus-visible {
   bottom: -1px;
   width: var(--pipe-rail-thickness);
   transform: translateX(-50%);
-  background: linear-gradient(180deg, rgba(15, 181, 255, 0.94), rgba(10, 142, 160, 0.78));
+  background: linear-gradient(
+    180deg,
+    rgba(15, 181, 255, 0.94),
+    rgba(10, 142, 160, 0.78)
+  );
   box-shadow: 0 0 8px rgba(0, 229, 255, 0.16);
   transition:
     background 120ms ease,
@@ -446,7 +487,11 @@ a:focus-visible {
   top: 50%;
   height: var(--pipe-rail-thickness);
   transform: translateY(-50%);
-  background: linear-gradient(90deg, rgba(15, 181, 255, 0.94), rgba(10, 142, 160, 0.78));
+  background: linear-gradient(
+    90deg,
+    rgba(15, 181, 255, 0.94),
+    rgba(10, 142, 160, 0.78)
+  );
   box-shadow: 0 0 8px rgba(0, 229, 255, 0.16);
   transition:
     background 120ms ease,
@@ -479,7 +524,11 @@ a:focus-visible {
 .pipe-nav-item:hover .nav-rail-cell-last::after,
 .pipe-nav-item.current .nav-rail-cell::before,
 .pipe-nav-item.current .nav-rail-cell-last::after {
-  background: linear-gradient(180deg, rgba(255, 154, 46, 0.98), rgba(255, 92, 255, 0.72));
+  background: linear-gradient(
+    180deg,
+    rgba(255, 154, 46, 0.98),
+    rgba(255, 92, 255, 0.72)
+  );
   box-shadow: 0 0 10px rgba(255, 154, 46, 0.22);
 }
 .pipe-nav-item:hover .nav-link-label,
@@ -631,7 +680,11 @@ table {
   display: block;
   overflow: auto;
   border: var(--double-border-soft);
-  background: linear-gradient(180deg, rgba(3, 17, 31, 0.98), rgba(0, 0, 0, 0.98));
+  background: linear-gradient(
+    180deg,
+    rgba(3, 17, 31, 0.98),
+    rgba(0, 0, 0, 0.98)
+  );
   box-shadow: var(--panel-glow);
 }
 th,
@@ -649,7 +702,11 @@ blockquote {
   padding: 12px 14px;
   border-left: 3px double var(--accent-orange);
   background:
-    radial-gradient(circle at top left, rgba(255, 92, 255, 0.08), transparent 36%),
+    radial-gradient(
+      circle at top left,
+      rgba(255, 92, 255, 0.08),
+      transparent 36%
+    ),
     linear-gradient(180deg, rgba(12, 8, 24, 0.98), rgba(0, 0, 0, 0.98));
   border-radius: 0;
   box-shadow: var(--panel-glow);